feat(insights): define storage contract and scoped reports

.changeset/browse-all-insights-events.md

@@ -4,9 +4,7 @@
 ---
 
 Add Overview / Events navigation in Insights to browse event history without
-an installation search, reporting-period filter, or bundle filter. Include all
-event types in newest-first order, with pagination, refresh, and links to
-installation history that preserve the source page and scroll position. Use
-readable local timestamps, copyable short identifiers, and semantic event
-labels and colors. Keep the existing Insights scan limit and report an
-error rather than silently returning partial history when it is exceeded.
+an installation search or bundle filter. Include all event types in newest-first
+order with cursor pagination, refresh, and links to installation history that
+preserve the source page and scroll position. Use readable local timestamps,
+copyable short identifiers, semantic event labels, and responsive mobile cards.

.changeset/define-insights-storage-contract.md

@@ -0,0 +1,35 @@
+---
+"@hot-updater/plugin-core": minor
+"@hot-updater/server": minor
+"@hot-updater/console": minor
+"@hot-updater/aws": minor
+"@hot-updater/cloudflare": minor
+"@hot-updater/firebase": minor
+"@hot-updater/postgres": minor
+"@hot-updater/supabase": minor
+"@hot-updater/cli-tools": patch
+"@hot-updater/mock": minor
+"@hot-updater/test-utils": minor
+---
+
+Define the required Insights persistence contract as `record`, `listEvents`,
+object-based `findInstallations`, `countInstallations`, and `countEvents`. Core
+owns report preparation, filters, windows, cursors, and summaries; providers
+implement atomic report/latest-state storage, fixed indexed queries, and scalar
+counts. Duplicate event IDs are first-write-wins and never update installation
+state again.
+
+Add scoped recent-reporting counts and selected-bundle applied, recovered-from,
+and adopted report counts with matching event drill-down in Console. Recovery
+from B to A belongs to B's recovery count while latest state names A. Counts
+remain independent live measurements and do not claim an exact share or success
+rate.
+
+Include all Insights indexes and native writers in the initial `1.0.0` schema.
+MongoDB Insights requires native transactions on a replica set or sharded
+cluster. Regenerate standalone ORM schemas and apply emitted Prisma collation
+SQL where required.
+
+Prisma SQL Server Insights explicitly rejects before database I/O because its
+string identity/order semantics do not meet this contract; other models remain
+available. MongoDB counts require version 5+ snapshot reads.

.detoxrc.js

@@ -38,7 +38,7 @@ module.exports = {
         process.env.HOT_UPDATER_E2E_ANDROID_TEST_BINARY_PATH ||
         "examples/v0.85.0/android/app/build/outputs/apk/androidTest/release/app-release-androidTest.apk",
       build:
-        `cd examples/v0.85.0/android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release -PreactNativeArchitectures=${androidArchitectures} -PHOT_UPDATER_E2E_DEBUGGABLE=true -PMIN_BUNDLE_ID=00000000-0000-7000-8000-000000000000`,
+        `cd examples/v0.85.0/android && ./gradlew --no-daemon :app:assembleRelease :app:assembleReleaseAndroidTest -Pkotlin.compiler.execution.strategy=in-process -DtestBuildType=release -PreactNativeArchitectures=${androidArchitectures} -PHOT_UPDATER_E2E_DEBUGGABLE=true -PMIN_BUNDLE_ID=00000000-0000-7000-8000-000000000000`,
     },
   },
   devices: {

docs/architecture/insights.md

@@ -1,8 +1,8 @@
 # Built-in Insights
 
-Insights is a first-party server domain backed by the official
-`database.models.insights` port. It is not a server plugin and does not declare its
-own provider, schema lifecycle, or universal component adapter.
+Insights is a server domain backed by `database.models.insights`. The database
+stores immutable reports and one latest report per installation; the server
+assembles operational views and selected-bundle deployment evidence.
 
 ```ts
 createHotUpdater({
@@ -11,36 +11,97 @@ createHotUpdater({
 });
 ```
 
-`createHotUpdater` always mounts event ingestion on `handlers.client` and
-Insights queries on `handlers.admin`. React Native clients send automatic
-lifecycle reports by default and can opt out with
-`HotUpdater.init({ insights: false })`.
-API keys authenticate event ingestion, Release Catalog, and artifact
-requests, but they do not grant Insights query access.
+`createHotUpdater` mounts ingestion on `handlers.client` and queries on
+`handlers.admin`. The admin handler does not authenticate itself: mount it
+behind framework authentication, or call the Insights provider from an
+authenticated server surface, as the Console does. API keys authorize client
+requests and ingestion, not admin queries. React Native sends lifecycle reports
+by default; `HotUpdater.init({ insights: false })` opts out.
 
-The admin handler does not authenticate itself. Mount it only behind framework
-authentication, or use the database-backed Insights provider directly from an
-authenticated server surface, as the Console does.
+## Provider responsibility
 
-`clientAccess` is a required, explicit authentication policy.
-Client update and Insights ingestion routes are always present on
-`handlers.client`, while mounting `handlers.admin` is the explicit opt-in for
-admin HTTP routes.
+Custom database authors implement five operations, all with object inputs:
 
-The database plugin owns physical storage and migration for `bundle_events`.
-The server owns event input validation, bounded scans, aggregation, installation
-search, and HTTP responses. Every database provider therefore exposes the same
-logical persistence contract:
+| Method                                                                  | Responsibility                                                                |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `record({ event, installation })`                                       | Atomically store the event and advance latest state; first event ID wins      |
+| `listEvents({ filter, sinceMs, beforeReceivedAtMs, after, limit })`     | Indexed newest-first global, installation-movement, or bundle-outcome history |
+| `findInstallations({ installId } or { userId, afterInstallId, limit })` | Exact latest-state lookup or current-user page                                |
+| `countInstallations({ platform, channel, sinceMs, bundleId })`          | Count recent latest rows, optionally naming one bundle                        |
+| `countEvents({ filter, sinceMs, beforeReceivedAtMs })`                  | Count accepted reports matching one raw bundle/type/scope filter              |
 
-```ts
-models: {
-  insights: {
-    append(row): Promise<void>;
-    scan({ beforeReceivedAtMs, after, limit }): Promise<readonly BundleEventRow[]>;
-  },
-}
-```
+The [custom database guide](../content/docs/%28latest%29/database-plugins/custom-database.mdx#insights)
+specifies ordering, atomicity, idempotency, visibility, pagination, and test
+requirements. Public types and boundary validation come from
+`@hot-updater/plugin-core`. The internal CRUD adapter is an implementation aid
+for bundled providers, not an additional interface that custom providers must
+implement.
+
+Core creates the report ID, receipt time, and full installation candidate. It
+owns movement semantics, scope/window selection, opaque cursors, and UI labels.
+Providers translate fixed predicates and persist data; they do not implement
+summary objects, outcome classifications, percentages, top-N groups, or charts.
+
+## Product views
+
+The Console provides:
+
+- scoped reporting-installation counts over 24 hours, 7 days, or 30 days;
+- selected-bundle reporting installations plus applied, recovered-from, and
+  adopted report counts;
+- outcome drill-down using exactly the same scope and receipt interval;
+- all-event browsing and exact installation/current-user lookup;
+- bundle movement history for a selected installation.
+
+`getReportingOverview({ platform, channel, window, bundleId? })` returns one
+scope measurement and, when a bundle is selected, four bundle measurements.
+Each scalar has `count` and `measuredAtMs`. The response also includes `sinceMs`
+and `beforeReceivedAtMs`, which bind outcome drill-down pages. The admin HTTP
+route is `GET /overview` relative to the admin handler mount. The global event
+method is `listEvents`; exact installation lookup takes `{ installId }`.
+
+Recovery from B to A contributes a recovered-from report to B, while the latest
+installation row names A. Adoption of a Release with the same bundle contributes
+an adoption report, not an application. `UNCHANGED` reports update latest state
+but do not increment those outcome counters.
+
+Counts describe reports received by the server, not all devices or unique
+update attempts. Offline devices and failed sends are absent. Independent live
+counts do not establish an exact share, success rate, or deployment completion.
+The UI displays them independently and does not clamp them into a ratio.
+
+Event pages sort descending by `(received_at_ms, id)`, apply filters before a
+limit of at most 101, and use an exclusive keyset cursor. Receipt intervals are
+`[sinceMs, beforeReceivedAtMs)`. Native continuation pages must be exhausted
+before returning a short result. Core does not aggregate raw history. The
+Console keeps previous cursors in session memory; only the current cursor and
+filter bounds appear in its URL.
+
+Latest-state counts never read event history. DynamoDB traverses canonical
+installation IDs so an installation cannot be counted twice when its last-report
+time advances. Its cost grows with stored installation rows, including rows
+outside the selected window. Other providers use native aggregate queries;
+returning one scalar does not imply constant work or latency.
+
+## Initial storage setup
+
+Schema `1.0.0` includes atomic storage and every Insights access path from the
+first initialization. Standalone SQL tooling initializes empty storage and
+leaves an initialized `1.0.0` database unchanged. Generate ORM schema artifacts
+before deployment. Prisma PostgreSQL/MySQL require the emitted companion
+collation SQL. MongoDB requires version 5 or later on a replica set or sharded
+cluster for native transactions and snapshot counts.
+
+Secondary indexes may lag. Exact installation reads use canonical state;
+current-user queries validate index candidates against that state so an old
+association is not returned. Newly assigned users can briefly have missing
+results. Counts and pages become complete once writes and indexes converge;
+a fixed receipt cutoff is not a commit watermark or a cross-request snapshot.
+
+## SQL Server limitation
 
-Scans are ordered by `(received_at_ms, id)` and are capped at 50,000 matching
-rows to keep built-in aggregation bounded. The Console reads the same server
-domain and no longer binds a separate Insights package or provider.
+The Prisma SQL Server adapter retains its other models, but its five Insights
+methods reject before database I/O. SQL Server's padded string equality can
+merge IDs that differ by trailing spaces; its default Unicode/UUID ordering
+also differs from this contract. There is no silent fallback to weaker identity
+or pagination semantics. Use a supported Insights provider for these views.

docs/content/docs/(latest)/database-plugins/aws.mdx

@@ -17,7 +17,7 @@ For AWS installations created by `npx hot-updater init`, DynamoDB is selected
 by default and this table is created or validated automatically.
 
 For custom installations, create one on-demand table manually with the
-overloaded index used for update checks and patch relations:
+overloaded index used for patch relations and installation movement history:
 
 ```bash
 aws dynamodb create-table \
@@ -170,10 +170,9 @@ const hotUpdater = createHotUpdater({
 
 The Lambda or server role needs `Query` access to the update index,
 `BatchGetItem`/`GetItem` access to Bundle, patch, and API key partitions,
-and `PutItem`/`Query` access to the Insights event partition. CLI and Console
-writers need the transaction and write permissions required to manage Bundle
-metadata and API keys. The AWS adapter does not impose an Insights
-retention period.
+and `GetItem`/`Query`/`TransactWriteItems` access to Insights partitions. CLI
+and Console writers need the transaction and write permissions required to
+manage Bundle metadata and API keys.
 
 The provider does not impose a total bundle, patch, or patch-relationship count
 limit. Each serialized metadata item is limited to 8 KiB, and counters and