rigscope 0.1.7 → 0.2.0

package/dist/system.cjs

@@ -789,6 +789,13 @@ async function enrollCollector(path, connectUrl, enrollmentToken, sharing, repla
 // src/hub/config.ts
 var import_node_net = require("node:net");
 var import_node_path3 = require("node:path");
+
+// src/contracts/telemetry.ts
+var MAX_PERSISTENT_FLUSH_MS = 5e3;
+var MIN_EPOCH = Date.parse("2000-01-01T00:00:00Z");
+var MAX_EPOCH = Date.parse("2200-01-01T00:00:00Z");
+
+// src/hub/config.ts
 var MAX_HUB_COLLECTORS_BYTES = 1024 * 1024;
 var MAX_COLLECTOR_ID_LENGTH = 128;
 var MAX_MACHINE_ID_LENGTH = 128;
@@ -816,6 +823,7 @@ function parseHubConfig(env) {
     maxCollectorConnections = parsed;
   }
   const connectionBudget = maxCollectorConnections === void 0 ? {} : { maxCollectorConnections };
+  const history = parseHistoryConfig(env);
   if (publicOrigin === void 0 !== (socketPath === void 0)) {
     throw new HubConfigError(
       "HUB_PUBLIC_ORIGIN and HUB_SOCKET_PATH must be set together: remote mode needs both the exact HTTPS origin and the Unix socket path"
@@ -835,6 +843,7 @@ function parseHubConfig(env) {
       collectors,
       development,
       remote: parseRemoteConfig(publicOrigin, socketPath),
+      history,
       ...connectionBudget
     };
   }
@@ -844,9 +853,65 @@ function parseHubConfig(env) {
     collectors,
     development,
     remote: null,
+    history,
     ...connectionBudget
   };
 }
+var DEFAULT_MEMORY_BUDGET_BYTES = 128 * 1024 * 1024;
+var DEFAULT_PERSISTENT_FLUSH_MS = MAX_PERSISTENT_FLUSH_MS;
+var DEFAULT_RECORDING_MAX_DURATION_MS = 60 * 6e4;
+var DEFAULT_RECORDING_MAX_BYTES = 64 * 1024 * 1024;
+var DEFAULT_RECORDING_BACKLOG_MS = 10 * 6e4;
+var DEFAULT_MAX_ACTIVE_RECORDINGS = 4;
+var HOUR_MS = 36e5;
+var DAY_MS = 864e5;
+function parseHistoryConfig(env) {
+  const modeValue = env.HUB_TELEMETRY_MODE ?? "memory";
+  if (modeValue !== "memory" && modeValue !== "persistent") {
+    throw new HubConfigError("HUB_TELEMETRY_MODE must be memory or persistent");
+  }
+  const memoryBudgetBytes = envInteger(
+    env.HUB_HISTORY_MEMORY_BYTES,
+    DEFAULT_MEMORY_BUDGET_BYTES,
+    1 * 1024 * 1024,
+    16 * 1024 * 1024 * 1024,
+    "HUB_HISTORY_MEMORY_BYTES"
+  );
+  const flushIntervalMs = envInteger(
+    env.HUB_TELEMETRY_FLUSH_MS,
+    DEFAULT_PERSISTENT_FLUSH_MS,
+    1e3,
+    MAX_PERSISTENT_FLUSH_MS,
+    "HUB_TELEMETRY_FLUSH_MS"
+  );
+  const retention = {
+    rawMs: envInteger(env.HUB_RETENTION_RAW_MS, 2 * DAY_MS, 0, 400 * DAY_MS, "HUB_RETENTION_RAW_MS"),
+    tenSecondMs: envInteger(env.HUB_RETENTION_10S_MS, 2 * HOUR_MS, 0, 30 * DAY_MS, "HUB_RETENTION_10S_MS"),
+    oneMinuteMs: envInteger(env.HUB_RETENTION_1M_MS, 30 * DAY_MS, 0, 400 * DAY_MS, "HUB_RETENTION_1M_MS"),
+    oneHourMs: envInteger(env.HUB_RETENTION_1H_MS, 400 * DAY_MS, 0, 800 * DAY_MS, "HUB_RETENTION_1H_MS"),
+    receiptsMs: envInteger(env.HUB_RECEIPT_RETENTION_MS, 7 * DAY_MS, HOUR_MS, 400 * DAY_MS, "HUB_RECEIPT_RETENTION_MS"),
+    gapsMs: envInteger(env.HUB_GAP_RETENTION_MS, 400 * DAY_MS, 0, 800 * DAY_MS, "HUB_GAP_RETENTION_MS")
+  };
+  const recordings = {
+    directory: nonEmpty(env.HUB_RECORDINGS_DIR) ?? null,
+    maxDurationMs: envInteger(env.HUB_RECORDING_MAX_DURATION_MS, DEFAULT_RECORDING_MAX_DURATION_MS, 1e3, 24 * 60 * 6e4, "HUB_RECORDING_MAX_DURATION_MS"),
+    maxBytes: envInteger(env.HUB_RECORDING_MAX_BYTES, DEFAULT_RECORDING_MAX_BYTES, 64 * 1024, 1024 * 1024 * 1024, "HUB_RECORDING_MAX_BYTES"),
+    backlogMs: envInteger(env.HUB_RECORDING_BACKLOG_MS, DEFAULT_RECORDING_BACKLOG_MS, 0, 24 * 60 * 6e4, "HUB_RECORDING_BACKLOG_MS"),
+    maxActive: envInteger(env.HUB_RECORDING_MAX_ACTIVE, DEFAULT_MAX_ACTIVE_RECORDINGS, 1, 32, "HUB_RECORDING_MAX_ACTIVE")
+  };
+  return { mode: modeValue, memoryBudgetBytes, flushIntervalMs, retention, recordings };
+}
+function envInteger(raw, fallback, min, max, name) {
+  if (raw === void 0 || raw === "") return fallback;
+  if (!/^\d+$/.test(raw)) {
+    throw new HubConfigError(`${name} must be a nonnegative integer`);
+  }
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new HubConfigError(`${name} must be between ${min} and ${max}`);
+  }
+  return value;
+}
 function nonEmpty(value) {
   return value === void 0 || value === "" ? void 0 : value;
 }

package/docs/configuration.md

@@ -17,7 +17,21 @@ configuration files at `0600`; do not commit them.
 | --- | --- |
 | `HUB_HOST`, `HUB_PORT` | Local listener: `127.0.0.1:8081`. Only literal loopback addresses are accepted. Port `0` selects an unused port for tests. |
 | `HUB_PUBLIC_ORIGIN`, `HUB_SOCKET_PATH` | Remote access: set both the exact HTTPS origin and an absolute Unix socket path in a private directory. The hub then has no TCP listener. |
-| `HUB_DATABASE_PATH` | SQLite database for telemetry, users, alerts and the collector registry. Defaults beside `HUB_STATE_FILE`, or under `$XDG_STATE_HOME/rigscope/hub/` (falling back to `~/.local/state`). |
+| `HUB_DATABASE_PATH` | SQLite database for control state (users, alerts and the collector registry) and, only when enabled, telemetry history. Defaults beside `HUB_STATE_FILE`, or under `$XDG_STATE_HOME/rigscope/hub/` (falling back to `~/.local/state`). |
+| `HUB_TELEMETRY_MODE` | `memory` (default) keeps bounded history in RAM and writes no routine telemetry rows. `persistent` opts into compact SQLite summaries. See [telemetry storage](telemetry-storage.md). |
+| `HUB_HISTORY_MEMORY_BYTES` | Global RAM budget for memory history. Default `134217728` (128 MiB). |
+| `HUB_TELEMETRY_FLUSH_MS` | Persistent-mode write interval. Default and maximum `5000` ms (5 seconds); allowed 1000–5000. The bound keeps one commit inside the 64-batch collector window at the fastest supported 100 ms cadence and well below the collector's 30 s ack timeout. |
+| `HUB_RETENTION_RAW_MS` | Persistent raw-mode retention. Default 2 days. Persistent summary mode does not write raw rows. |
+| `HUB_RETENTION_10S_MS` | Ten-second summary retention in persistent mode. Default 2 hours. |
+| `HUB_RETENTION_1M_MS` | One-minute rollup retention. Default 30 days. |
+| `HUB_RETENTION_1H_MS` | One-hour rollup retention. Default 400 days. |
+| `HUB_RECEIPT_RETENTION_MS` | Deduplication receipt lifetime, independent of chart retention. Default 7 days. |
+| `HUB_GAP_RETENTION_MS` | Explicit collector gap retention. Default 400 days. |
+| `HUB_RECORDINGS_DIR` | Private directory for explicit recordings. Default `recordings/` beside the hub database (0700 directory, 0600 files). |
+| `HUB_RECORDING_MAX_DURATION_MS` | Maximum recording duration. Default 1 hour; maximum 24 hours. |
+| `HUB_RECORDING_MAX_BYTES` | Maximum recording file size. Default 64 MiB; maximum 1 GiB. |
+| `HUB_RECORDING_BACKLOG_MS` | Recent RAM history a new recording may include. Default 10 minutes. |
+| `HUB_RECORDING_MAX_ACTIVE` | Concurrent active recordings. Default 4; maximum 32. |
 | `HUB_BROWSER_USERS` | First-run users as JSON: `{username,passwordHash,machineIds,admin?}`. `machineIds` is `"*"` or a list; `[]` allows no machines. |
 | `HUB_ADMIN_USERS` | Comma-separated usernames to make administrators during first import. If omitted, an existing bootstrap account named `owner` becomes an administrator. Other users need an explicit `admin:true`. |
 | `HUB_COLLECTORS` | First-run collector credentials as JSON: `{collectorId,machineId,token}`. The limit applies to JSON bytes, not a fixed machine count. |
@@ -25,6 +39,24 @@ configuration files at `0600`; do not commit them.
 | `HUB_STATE_FILE` | Private enrollment file to import from an existing installation; also enables enrollment. Keep it with the deployment configuration for recovery. |
 | `HUB_ENROLLMENT_GRANTS` | Initial grants as JSON: `{token,expiresAt}`. Expiry must be within 15 minutes. Used grants stay consumed after import and restart. |
 
+### Telemetry history mode
+
+The default `HUB_TELEMETRY_MODE=memory` keeps recent charts in a bounded RAM
+budget and deliberately loses telemetry history when the hub restarts. Users,
+credentials, enrollment, settings and alert records remain in SQLite.
+
+Set `HUB_TELEMETRY_MODE=persistent` to keep compact ten-second summaries, with
+one transaction roughly every `HUB_TELEMETRY_FLUSH_MS` (five seconds by
+default). Collectors still acknowledge only after that transaction commits, so
+the flush interval cannot exceed the collector's 64-batch in-flight window at
+its advertised cadence; the hub rejects values above five seconds. See
+[telemetry storage](telemetry-storage.md) for aggregation, deduplication,
+recording and reset details.
+
+Switching an existing installation to memory mode does not automatically delete
+old telemetry rows. They are ignored, but can be reclaimed explicitly with
+`ops reset-telemetry` after stopping the hub (see [operations](operations.md)).
+
 ### First-run users and credentials
 
 The database imports bootstrap users and collector credentials once. Later

package/docs/installation.md

@@ -27,7 +27,7 @@ install or source checkout is needed. The launcher and services use the installe
 runtime, so removing the npx cache does not break them.
 
 Releases are on [npm](https://www.npmjs.com/package/rigscope). `@latest` selects
-the current stable release; replace it with `@0.1.7` to select that exact version.
+the current stable release; replace it with `@0.2.0` to select that exact version.
 
 ### Installation options
 
@@ -53,7 +53,7 @@ For a downloaded package or one built from source, run from the directory
 containing the archive, or give its absolute path:
 
 ```sh
-npx --yes --package ./rigscope-0.1.7.tgz rigscope install --boot
+npx --yes --package ./rigscope-0.2.0.tgz rigscope install --boot
 ```
 
 The same installation options apply. npm still needs registry access or cached
@@ -295,7 +295,7 @@ settings and collector identities.
 
 | Alternative | Command |
 | --- | --- |
-| Select an exact published version | `rigscope upgrade --from rigscope@0.1.7` |
+| Select an exact published version | `rigscope upgrade --from rigscope@0.2.0` |
 | Install a local archive | `rigscope upgrade --from ./rigscope-VERSION.tgz` |
 | Return to the retained previous runtime | `rigscope rollback` |
 

package/docs/monitoring.md

@@ -20,22 +20,58 @@ driver and readable counters; see [Hardware](installation.md#hardware) and
 
 ## History and delivery
 
-The hub acknowledges samples after committing them to SQLite. A collector keeps
-unacknowledged samples in a persistent queue for each hub and retries after a
-disconnect. The hub removes duplicates using the collector, run and sequence IDs.
+History is **RAM-only by default**. Live readings update immediately, recent
+charts come from a bounded memory budget, and telemetry history disappears when
+the hub restarts. Users, credentials, enrollment, settings, alert records,
+machine names/tags and inventory remain persistent.
+
+In memory mode the collector's acknowledgement means the hub accepted the sample
+into RAM. The collector keeps the same durable outbox and retries after a
+disconnect; it does not gain extra disk work from the hub's choice. Deduplication
+uses a compact per-run interval set for the hub process lifetime. Because both
+history and receipts disappear together on restart, a replay cannot double-count
+restored chart data.
+
+Set `HUB_TELEMETRY_MODE=persistent` to opt into disk history. The hub buffers a
+five-second window, publishes live state immediately, writes one compact
+transaction, and only then acknowledges. Replay deduplication uses durable
+receipts whose lifetime is independent of chart retention (default seven days).
 Replayed samples fill History without replacing current live readings or opening
-alerts for past threshold crossings.
+alerts for past threshold crossings. A graceful shutdown flushes pending
+summaries; after a crash the collector replays anything that was never committed.
 
-Default retention:
+Default memory history:
 
 | Resolution | Kept for |
 | --- | --- |
-| Raw samples | 48 hours |
-| One-minute summaries | 30 days |
-| One-hour summaries | 400 days |
-
-Summaries retain minimum and maximum values. History queries limit the number
-of points, series, scanned rows and time spent. The UI marks partial results.
+| 1-second detail | 2 minutes |
+| 10-second summaries | 1 hour |
+| One-minute summaries | 24 hours |
+| One-hour summaries | 7 days |
+
+Per-core CPU keeps less detail; machine-wide and capacity metrics keep more.
+Persistent mode writes compact ten-second summaries and folds them into
+one-minute and one-hour tiers; it does not write a raw row per reading. It keeps
+10-second summaries for 2 hours, one-minute summaries for 30 days and hourly
+summaries for 400 days by default. Both modes retain minimum and maximum values,
+so short spikes remain visible, and both preserve explicit unavailable readings
+and gaps.
+
+RAM history is bounded by `HUB_HISTORY_MEMORY_BYTES` (default 128 MiB) across all
+machines. When the budget fills, the oldest fine-grained tiers are dropped first
+and new cardinality beyond the sustainable budget is rejected with visible
+pressure. History queries limit points, series, scanned rows and elapsed time;
+the UI marks partial results.
+
+### Recording
+
+Use **History → Recording** to start an explicit capture for the current
+machine and selected metrics. Choose a resolution from 1 second to 1 hour,
+a duration and whether to include recent RAM history. The capture is bounded by
+duration and bytes, survives restart through its private persisted output, and
+can be downloaded by its creator. Recording also works when chart history is
+temporary, which is the intended way to keep an incident snapshot. See
+[telemetry storage](telemetry-storage.md#recording).
 
 Hover over a History or Overview recent-usage chart to inspect a recorded time
 and its bucket averages. The time marker follows across charts in the same view;
@@ -49,11 +85,12 @@ Each collector queue keeps up to ten minutes or 64 MiB of queued JSON per hub,
 with a 256 MiB total JSON limit. Physical SQLite files, including WAL files,
 have separate limits of 80 MiB per hub and 640 MiB across eight hubs.
 
-The hub's default database limit is 2 GiB, including its WAL file and all tables.
-Retention protects the newest hour of telemetry. If old-data cleanup cannot
-free enough space, the hub stops acknowledging new samples and collectors retry.
-Existing oversized databases report pressure; startup does not run a destructive
-cleanup.
+In persistent mode the hub's default database limit is 2 GiB, including WAL and
+all control tables. Retention protects the newest hour; if old-data cleanup
+cannot free enough space, the hub stops acknowledging new samples and collectors
+retry. Existing oversized databases report pressure; startup does not run a
+destructive cleanup. In memory mode old historical rows may still occupy the
+file until you run `ops reset-telemetry`; they are not read or updated.
 
 These are application limits, not filesystem quotas. A transaction can briefly
 grow the WAL before checkpointing. Blocked checkpoints stop further ingestion
@@ -92,7 +129,10 @@ credentials persist in SQLite. Browser sessions stay in memory, expire after
 Alerts support above/below thresholds, durations, unavailable readings, missing
 receipts, maintenance and recovery. Value, unavailable and stale-receipt rules
 apply to the machines tracked by that hub. Replayed samples do not open past
-incidents.
+incidents. Alert rules, incidents and pending notifications stay durable in both
+history modes; with no rules configured, live ingestion does not write per-sample
+alert progress. Enabling rules may write alert state on evaluation, which is
+operational state rather than telemetry history.
 
 In **Alerts**, configure one HTTPS webhook channel. Its URL, headers and HMAC
 secret are write-only. Loopback HTTP is allowed for controlled test sinks.

package/docs/operations.md

@@ -10,6 +10,7 @@ building and deploying from source.
 | Reset a lost password | [Password recovery](#password-recovery) |
 | Change localhost/HTTPS access | [Access changes](#access-changes) |
 | Back up or restore a database | [Database commands](#database-commands) |
+| Discard old telemetry history only | [Database commands](#database-commands) |
 | Plan what to back up | [Consistent backup set](#consistent-backup-set) |
 | Handle a full database or queue | [Storage pressure recovery](#storage-budgets-and-pressure-recovery) |
 
@@ -369,6 +370,11 @@ node dist/ops.cjs restore \
   --database /path/telemetry.sqlite \
   --replace --confirm-stopped
 
+# Discard only telemetry history, preserving users/enrollment/settings/alerts.
+node dist/ops.cjs reset-telemetry \
+  --database /path/telemetry.sqlite \
+  --backup-dir /path/private-backups --confirm-stopped
+
 # Offline managed-user recovery; password comes from a private 0600 file.
 node dist/ops.cjs recover-admin \
   --database /path/telemetry.sqlite \
@@ -408,8 +414,9 @@ release must never be pointed at a newer schema. `inspect` reports this state.
 
 The database backup is not the whole installation. A restorable set is:
 
-1. Hub SQLite database: `telemetry.sqlite` (includes registry/admin/alerts).
-   Use `ops backup`; do not copy the main file alone while the hub is running.
+1. Hub SQLite database: `telemetry.sqlite` (includes registry/admin/alerts and
+   any opt-in persistent history). Use `ops backup`; do not copy the main file
+   alone while the hub is running.
 2. Enrollment/config state when configured: `HUB_STATE_FILE` (for
    example `hub/enrollment.json`, the import source for previously enrolled
    collectors) and the private hub environment file. These
@@ -420,6 +427,9 @@ The database backup is not the whole installation. A restorable set is:
    deduplicates by collector/run/sequence.
 5. Optional operational metadata: `install-state.json`, units and the built
    release. Keep the release matching the database schema for rollback.
+6. Explicit recordings: the private `HUB_RECORDINGS_DIR` (default
+   `<hub database directory>/recordings`) if you want downloadable captures to
+   survive a restore. They are user output, not part of the database backup.
 
 For a consistent set, prefer stopping both services cleanly, then run the online
 database backup and copy the other private files. For an online backup, the SQLite
@@ -486,7 +496,18 @@ node dist/ops.cjs measure --machines 2 --batches 30 --records-per-batch 5 \
 It writes synthetic records through the real `TelemetryStore` into a
 temporary private database and reports accepted/rejected/busy counts, ingestion
 latency, event-loop delay/utilization, RSS, database/WAL size, store queue and
-flush counters, and one history-query latency. The output is labelled synthetic.
+flush counters, and one history-query latency.
+
+For the history-mode tradeoff, use the repeatable RAM-vs-persistent benchmark.
+It measures process-attributed disk writes, latency, RSS and rows:
+
+```sh
+npm run benchmark:telemetry -- --machines 2 --seconds 120
+npm run benchmark:telemetry -- --machines 10 --seconds 60 --json
+```
+
+Use `--dir` on a real filesystem; tmpfs does not account storage writes in
+`/proc/self/io`. See [telemetry storage](telemetry-storage.md#benchmark). The output is labelled synthetic.
 Defaults are intentionally small; upper bounds are 1,000 machines, 2,000 batches,
 32 records per batch and 100,000 records total. It never opens a service socket
 or contacts a hub. `--keep` retains the temporary directory for inspection. The
@@ -536,12 +557,20 @@ cadence, inventory and metadata through Sample ingestion while retaining a
 disconnected state until an authenticated Collector reconnects.
 
 The default hub main-file plus WAL budget is 2 GiB, shared by every SQLite table.
-The main file has a page-count limit; WAL reserves up to 128 MiB inside that budget.
-Telemetry writes return busy on pressure or SQLITE_FULL, with no receipt/ack for a
-failed transaction. Retention reclaims old raw/one-minute points in bounded chunks
-while preserving the newest hour; hourly rollups retain their configured age window.
-A full newest-hour working set must fit the deployment's budget. Outboxes retry
-while the operator frees space or provisions a larger supported configuration.
+The main file has a page-count limit; WAL reserves up to 128 MiB inside that budget
+and automatic checkpointing waits for a meaningful 32–64 MiB reserve where the
+budget permits. Persistent-mode writes return busy on pressure or SQLITE_FULL,
+with no receipt/ack for a failed transaction. Retention reclaims old raw or
+ten-second points and one-minute rollups in bounded chunks while preserving the
+newest hour; hourly rollups retain their configured age window. A full
+newest-hour working set must fit the deployment's budget. Outboxes retry while
+the operator frees space or provisions a larger supported configuration.
+
+Memory mode keeps only a bounded RAM budget (`HUB_HISTORY_MEMORY_BYTES`, default
+128 MiB). It does not write routine telemetry rows, but existing historical rows
+from an older installation still occupy the database until removed with
+`ops reset-telemetry` while the hub is stopped. That command preserves users,
+credentials, enrollment, settings, alert state, metadata and inventory.
 
 Collector defaults are 64 MiB logical JSON and 80 MiB physical main+WAL per hub,
 256 MiB logical and 640 MiB physical across eight destinations. Physical pressure

package/docs/releasing.md

@@ -5,7 +5,7 @@ The first public version, `0.1.0`, is published 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.7` as an example. For a new release, substitute its
+The commands below use `0.1.8` as an example. For a new release, substitute its
 new version everywhere; do not attempt to republish an already published version.
 Documentation edits can be committed and pushed to GitHub independently. The published archive and
 its bundled documentation stay unchanged; ship updated package documentation
@@ -21,7 +21,7 @@ with the next version. Keep each release tag on the revision used to build 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.7`, push the tag, and create a GitHub
+6. Tag the exact source revision as `v0.1.8`, push the tag, and create a GitHub
    Release with the release notes, verified archive and checksum. Announce it
    after the registry installation works.
 
@@ -45,14 +45,14 @@ 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.7` in these
+archive. Reuse the archive for every check below. Replace `0.1.8` in these
 commands when releasing another version.
 
 ## Verify the exact archive
 
 ```sh
-node scripts/verify-package.cjs ./out/release/rigscope-0.1.7.tgz
-npm run verify:installed -- --archive ./out/release/rigscope-0.1.7.tgz
+node scripts/verify-package.cjs ./out/release/rigscope-0.1.8.tgz
+npm run verify:installed -- --archive ./out/release/rigscope-0.1.8.tgz
 npm test
 node scripts/test-runtime.cjs
 node scripts/test.cjs --suite development
@@ -69,9 +69,9 @@ 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.7.tgz" \
+RIGSCOPE_TEST_ARCHIVE="$PWD/out/release/rigscope-0.1.8.tgz" \
   node --import tsx --test tests/cli-install.integration.ts tests/cli-reset.integration.ts
-node scripts/verify-operations.cjs ./out/release/rigscope-0.1.7.tgz
+node scripts/verify-operations.cjs ./out/release/rigscope-0.1.8.tgz
 ```
 
 These cover installation, pairing, independent component controls, bootstrap
@@ -93,7 +93,7 @@ Record the final checksum after verification:
 
 ```sh
 cd out/release
-sha256sum rigscope-0.1.7.tgz > SHA256SUMS
+sha256sum rigscope-0.1.8.tgz > SHA256SUMS
 sha256sum --check SHA256SUMS
 ```
 
@@ -110,7 +110,7 @@ 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.7.tgz --access public --tag latest \
+npm publish ./out/release/rigscope-0.1.8.tgz --access public --tag latest \
   --registry=https://registry.npmjs.org --dry-run
 ```
 
@@ -120,12 +120,12 @@ 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.7.tgz --access public --tag latest \
+npm publish ./out/release/rigscope-0.1.8.tgz --access public --tag latest \
   --registry=https://registry.npmjs.org
-npm view rigscope@0.1.7 version dist.integrity --registry=https://registry.npmjs.org
+npm view rigscope@0.1.8 version dist.integrity --registry=https://registry.npmjs.org
 ```
 
-Then use `npx --yes rigscope@0.1.7 install` with a disposable `--state-dir`, an
+Then use `npx --yes rigscope@0.1.8 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.

package/docs/telemetry-storage.md

@@ -0,0 +1,187 @@
+# Telemetry storage, history and recording
+
+Rigscope has two explicit telemetry-history modes. The default is RAM-only.
+Persistent history is opt-in and writes compact summaries, not one row per
+collector reading.
+
+> "No persistent telemetry history" is accurate for memory mode. It is not a
+> promise of zero disk writes: hub logs, SQLite control state, alert state,
+> recordings and operating-system swap may still write.
+
+Configuration and non-history state always remain in SQLite: users, password
+hashes, sessions' audit records, collector enrollment and credentials, grants,
+alert rules/incidents/jobs/webhook settings, machine display names/tags, and
+inventory. Only telemetry history is ephemeral by default.
+
+## Modes
+
+| | `HUB_TELEMETRY_MODE=memory` (default) | `HUB_TELEMETRY_MODE=persistent` |
+| --- | --- | --- |
+| Live readings | Updated immediately in RAM | Updated immediately in RAM |
+| Recent charts | Bounded typed-array RAM rings | Compact worst-case summaries in SQLite |
+| Ack meaning | Accepted into hub RAM; intentional loss on restart | Committed transaction; durable delivery |
+| Restart | History and latest snapshots disappear | Summaries and latest snapshots restore |
+| Routine telemetry writes | None | One transaction roughly every 5 seconds |
+| Deduplication | Per-run in-RAM interval set | `sample_receipts` with an independent 7-day TTL |
+
+The hub sends `delivery: "memory"` or `"durable"` in `welcome`. Collectors keep
+the same durable per-destination outbox, retry and in-flight behavior in both
+cases, so delayed acknowledgements do not move sustained writes from the hub to
+the collectors.
+
+### Memory history defaults
+
+The RAM budget is `HUB_HISTORY_MEMORY_BYTES` (default **128 MiB**) for the whole
+hub, not per machine. Within it, each series keeps:
+
+| Tier | Default retention | Purpose |
+| --- | --- | --- |
+| 1 second | 2 minutes | Short incident lead-up |
+| 10 seconds | 1 hour | Recent troubleshooting |
+| 1 minute | 24 hours | Medium-term history |
+| 1 hour | 7 days | Longer-term trends |
+
+Per-core CPU uses shorter detail: 10-second buckets for 10 minutes, 1-minute for
+6 hours and 1-hour for 2 days. Other metrics use the table above.
+
+Each reading updates the current bucket of each applicable tier. Buckets keep
+`min`, `max`, `sum`, non-null `count` and an explicit unavailable `nullCount`, so
+a one-second spike is still represented after it is aggregated into a minute or
+hour. This is aggregation, not "keep every tenth sample". Empty buckets are
+omitted; an all-unavailable bucket renders as unknown, never zero.
+
+All current metrics are gauges or already-derived rates: the collector computes
+network/disk bytes per second from monotonic counters before sending, so the hub
+never averages a cumulative counter and does not need first/last values for rate
+reconstruction. If a cumulative counter metric is added later, it needs an
+explicit delta/first-last aggregation policy rather than this gauge path.
+
+When a new series would exceed the global budget, the least-recently-seen series
+lose their finest tiers first, then whole series are evicted. New cardinality
+that still does not fit is rejected and reported as pressure. This makes the
+budget finite even for a machine that adds hundreds of disks or cores.
+
+### Persistent summary history
+
+Persistent mode buffers ingestion and commits all series for roughly five
+seconds in one transaction. It writes `points_10s` plus folded one-minute and
+one-hour rollups. It does **not** write `points_raw` unless an operator
+explicitly constructs the store in raw mode (used by tests and measurement).
+
+- Live publication is decoupled from the commit, so the dashboard is not one
+  flush behind.
+- A sample is acknowledged only after `COMMIT` returns with `synchronous=FULL`.
+- Retries are deduplicated by `(collectorId, runId, sequence)` before any
+  point/rollup side effect. Committed records cannot be counted twice.
+- After a crash, uncommitted buffered samples are replayed by the collector
+  because they were never acknowledged. Committed samples have receipts.
+- A graceful shutdown flushes pending summaries before closing within the hub's
+  bounded shutdown window.
+- Late/replayed samples extend the correct immutable summary bucket; the
+  one-minute and one-hour rows receive only the new delta, never a recomputed
+  total. Out-of-order samples inside the retained RAM ring update the matching
+  completed bucket; samples older than the retained window are counted as late
+  and dropped rather than corrupting a newer bucket.
+- Buckets use absolute minute/hour boundaries. A query includes the current
+  partial window once, and a later query recomputes only that bucket from the
+  same summaries, so completed data is not double-counted.
+- Flush failures resolve pending batches as retry/busy, so collectors keep the
+  data and back off. The queue is bounded (`HUB` storage queue and the
+  collector's in-flight window) and does not grow without limit.
+- The collector's local in-flight window and the hub's welcome window are both
+  64 batches, the wire maximum. The hub's persistent flush interval is capped
+  at five seconds, which fits that window at the fastest supported 100 ms
+  cadence (6.4 s of coverage) and leaves 1.4 s for COMMIT/ack latency; it is
+  also far below the collector's 30-second per-batch ack timeout. The
+  collector reserves enough slots for a full flush window of live samples,
+  plus two samples of headroom, and drains a waiting live
+  record as soon as an acknowledgement frees capacity. Its durable outbox
+  keeps the existing 10-minute/64 MiB per-destination bounds, so delayed acks
+  do not turn into sustained collector writes or silent data movement.
+
+Dedup receipts default to **7 days** and are independent of chart retention.
+Shortening raw/10-second history can no longer let a replayed sample recreate
+expired chart data.
+
+### Which readers exist
+
+Charts, exports and recordings all use the same bounded history query interface,
+so memory and persistent modes do not have separate chart code. Query work is
+bounded by series count, scanned rows, elapsed time and output points. The
+finest tier whose retention covers the requested range is selected; an empty
+finer tier falls through to the next one (for example after upgrading an
+existing database).
+
+## Recording
+
+A recording is an explicit, bounded capture and is separate from chart history.
+
+- Start/stop from **History → Recording**.
+- Choose the current machine, selected metrics, resolution (1s, 10s, 1m, 5m or
+  1h), duration, and whether to include recent RAM history (the lead-up).
+- The hub writes private JSON-lines data under `HUB_RECORDINGS_DIR`
+  (default `<hub database directory>/recordings`, mode 0700 files 0600).
+- Recordings are bounded by `HUB_RECORDING_MAX_DURATION_MS` (default 1 hour) and
+  `HUB_RECORDING_MAX_BYTES` (default 64 MiB). A duration or size limit ends the
+  capture with an explicit reason.
+- Metadata survives restart. A capture active during a restart is marked
+  interrupted and its partial file stays downloadable.
+- Download/list/delete are authenticated and authorized to the creating account
+  (administrators can see all) and to the caller's current machine scope. The
+  browser names an opaque recording id; it can never name a filesystem path.
+
+Recordings are not part of a database-only backup. If they matter, include the
+recordings directory in the same private backup set as the hub database.
+
+## Reset old history
+
+Switching an existing installation to memory mode does not read or rewrite old
+telemetry rows, but they still occupy the database. To discard them explicitly
+while preserving users, enrollment, settings and alert state:
+
+```sh
+rigscope stop
+node dist/ops.cjs reset-telemetry \
+  --database /path/to/telemetry.sqlite \
+  --backup-dir /path/to/private-backups \
+  --confirm-stopped
+```
+
+The command deletes only `points_raw`, `points_10s`, `points_1m`, `points_1h`,
+`sample_receipts`, `gaps`, `machine_latest` and `series`. It refuses without
+`--confirm-stopped` and while the hub lock exists. It never drops the database
+file, users, collector registry, alert rules/incidents, metadata, inventory or
+recordings. `--backup-dir` is optional but recommended; a consistent backup is
+taken first when supplied.
+
+## Benchmark
+
+`npm run benchmark:telemetry -- --machines 2 --seconds 120` drives the real
+stores with a realistic ~186-series-per-machine, one-second payload. It reports
+process-attributed `/proc/self/io` write bytes (not database size), ingestion
+enqueue/commit latency, history-query latency, RSS, row counts and database
+size. `--json` prints machine-readable output; `--dir` selects a real filesystem
+because tmpfs does not account storage writes in `/proc/self/io`.
+
+One development-host result for **2 machines × 60 simulated seconds** (186
+series each) was:
+
+| Mode | Steady writes | Close/checkpoint | DB size | Commit p95 | History query |
+| --- | --- | --- | --- | --- | --- |
+| memory | **0.00 MiB** | 248 KiB | 0.3 MiB | 42 ms | 3.0 ms |
+| persistent summaries | **0.98 MiB** | 264 KiB | 1.2 MiB | 35 ms | 5.9 ms |
+| legacy raw, per-batch commit | 21.66 MiB | 692 KiB | 21.6 MiB | 15 ms | 6.8 ms |
+
+That run measured persistent summaries at about **0.05×** the legacy write
+volume (roughly 22× less) and memory mode at zero sustained ingestion writes.
+
+A second run with **10 machines** (1,860 series) and the default 128 MiB RAM
+budget reported `RAM 128/128 MiB pressure` while keeping all series readable
+through the coarser tiers: memory wrote 0.00 MiB, persistent summaries 4.05 MiB,
+and legacy raw 104.76 MiB of steady ingestion-phase writes. RSS peaks include
+the Node baseline and temporary query/flush allocations, so they are higher than
+the history-array budget.
+
+These numbers are development-host measurements, not a promised multiplier or
+capacity guarantee. Re-run on the deployment host and payload before choosing
+retention or budgets.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rigscope",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "private": false,
   "engines": {
     "node": ">=26.0.0"
@@ -22,6 +22,7 @@
     "test": "node scripts/test.cjs",
     "test:runtime": "npm run build:runtime && node scripts/test-runtime.cjs",
     "test:dev": "npm run build:runtime && node scripts/test.cjs --suite development",
+    "benchmark:telemetry": "tsx scripts/telemetry-benchmark.ts",
     "validate:https": "node scripts/validate-https.cjs",
     "build:ui": "next build --webpack",
     "rigscope": "node bin/rigscope.cjs",
@@ -70,6 +71,7 @@
     "docs/system-installation.md",
     "docs/configuration.md",
     "docs/monitoring.md",
+    "docs/telemetry-storage.md",
     "docs/operations.md",
     "docs/bottlenecks.md",
     "docs/exports.md",