cursedbelt-server 4.18.0 → 4.19.0

package/dist/server/engagement/policy.js

@@ -0,0 +1,202 @@
+/**
+ * The rules that decide what a place-view is allowed to say — pure, so every
+ * one of them is a test rather than a comment.
+ *
+ * ── Why product analytics is a SEPARATE thing from `metrics/` ───────────────
+ * `metrics/` answers "is the fleet healthy": throughput, latency, status codes,
+ * 5xx, memory. Its store header makes a promise in capital letters — no user
+ * id, no query string, no path — and that promise is what makes it safe to run
+ * the same middleware inside the zero-knowledge vault and the owner's notes.
+ *
+ * This module answers a different question the owner actually asked: "who uses
+ * what apps, popularity stats, which users like what features/apps, and what is
+ * holding and not holding interest". That question is USER-KEYED by definition,
+ * so it cannot live behind that promise — and weakening the promise to make
+ * room for it would quietly re-point twelve apps' request log at a user id.
+ * Two stores, two guarantees, one of which stays absolute.
+ *
+ * ── The privacy design, in three rules ──────────────────────────────────────
+ * 1. **A place is an ALLOWLISTED id, never a path.** The allowlist is the app's
+ *    own `routes.manifest.json` — the list it already maintains for the route
+ *    health check. Anything not on it records as `OTHER_PLACE`. So a note id, a
+ *    ROM title, a vault entry name or a search string cannot become a place
+ *    even if a caller tries: there is no code path from request text to a
+ *    stored string. This is structural, not a sanitizer that can be outgrown.
+ * 2. **Some apps are excluded by NAME, in the kit.** `apps/vault` is
+ *    zero-knowledge by construction and `fractals`/`patterns` are public with
+ *    no accounts at all. Making that a per-app config would mean the vault's
+ *    protection was "somebody remembered"; making it a refusal here means an
+ *    agent who wires the beacon into the vault gets a no-op and a red gate.
+ * 3. **Counts and clocks only.** A row is (user, place, day) → views, active
+ *    ms, sessions, first/last. There is no event log, so there is nothing to
+ *    correlate against and nothing to leak beyond "this account opened this
+ *    page N times that day".
+ *
+ * ── Honest at n = 3 ─────────────────────────────────────────────────────────
+ * This fleet has one real user plus family. Every number here is one a human
+ * can check by hand: whole counts, whole days, an explicit "never opened", and
+ * a drop-off signal stated in days rather than as a rate. Nothing is a ratio
+ * over a denominator of two.
+ */
+/** The bucket a view lands in when its place is not on the app's allowlist. */
+export const OTHER_PLACE = "other";
+/**
+ * Apps that must never record engagement, whatever they ask for.
+ *
+ * 🔴 Do not turn this into a config option. See rule 2 in the file header: the
+ * point is that the vault's exclusion cannot be forgotten, mis-set, or lost in
+ * a merge. `scripts/engagementRoster.test.ts` fails if one of these ever mounts
+ * the recorder.
+ */
+export const ENGAGEMENT_EXCLUDED_APPS = [
+    // Zero-knowledge by construction. The server stores opaque ciphertext and
+    // must not learn even which pages the owner spends time on — a per-place
+    // dwell profile over a password manager is a map of which credentials
+    // matter, which is exactly the thing the design refuses to hold.
+    "vault",
+    // Public, no accounts, no session — there is no user to key a row on, and
+    // tsk_01KZN61WJ8X15SKGPMFABBJ889 exists because an analytics beacon reached
+    // somewhere it had no business being. A public app gets request metrics.
+    "fractals",
+    "patterns",
+    // The dev-only host-header proxy. Never deployed, serves no pages of its own.
+    "gateway",
+];
+/** Is this app allowed to record engagement at all? */
+export function engagementAllowedForApp(app) {
+    return !ENGAGEMENT_EXCLUDED_APPS.includes(app.trim().toLowerCase());
+}
+/**
+ * Resolve what a browser reported to one of the app's declared places.
+ *
+ * A caller may send either the place ID (an app that knows its own route
+ * names) or the LOCATION it is at (`#/calendar`, `/#/t/scifi`) — and the
+ * location form is the one that matters, because it is what lets twelve apps
+ * adopt the beacon without each writing a `route.view → place id` mapping that
+ * can drift. Everything unrecognized collapses to {@link OTHER_PLACE}.
+ *
+ * 🔴 A `:param` segment matches ANY single segment and contributes NOTHING to
+ * what is stored: `/#/t/my-divorce-reading-list` resolves to the id `tracker`,
+ * and the shelf name is discarded here, before any database sees it. That is
+ * the mechanism behind rule 1 in the file header — the parameterized routes are
+ * exactly the ones whose URLs carry user content, so they are exactly the ones
+ * that must reduce to a name.
+ */
+export function resolvePlace(claimed, allowed) {
+    // NOT short-circuited on empty: the home page normalizes to `""` from both
+    // sides (the manifest writes it `/`, a browser reports `/` or `#/`), so the
+    // root is a legitimate match rather than a missing value. An app whose
+    // manifest declares no root still gets `other` from the loop below.
+    const want = normalizePlaceId(claimed);
+    const wantSegments = want.split("/");
+    for (const entry of allowed) {
+        const ref = typeof entry === "string" ? { id: entry, path: "" } : entry;
+        if (normalizePlaceId(ref.id) === want)
+            return ref.id;
+        if (ref.path && pathMatches(ref.path, wantSegments))
+            return ref.id;
+    }
+    return OTHER_PLACE;
+}
+/** Does `segments` match this manifest path, treating `:param` as a wildcard? */
+function pathMatches(manifestPath, segments) {
+    const pattern = normalizePlaceId(manifestPath);
+    // The manifest writes the home page as `/`, which normalizes to the empty
+    // string — and so does a browser sitting at `/` or `#/`. Both are one empty
+    // segment, so the generic comparison below already agrees; this is only here
+    // to say that the empty case is intended rather than an accident.
+    const parts = pattern.split("/");
+    if (parts.length !== segments.length)
+        return false;
+    return parts.every((part, i) => part.startsWith(":") || part === segments[i]);
+}
+/**
+ * `#/deep/Link` → `deep/link`. Exported for the tests that pin rule 1.
+ *
+ * The leading `/#` a manifest path carries and the bare `#` a browser reports
+ * are both stripped, because `/#/calendar`, `#/calendar` and `/calendar` are
+ * one page and three spellings — and three spellings would read as three
+ * unpopular features rather than one popular one.
+ */
+export function normalizePlaceId(raw) {
+    return (raw
+        .trim()
+        .toLowerCase()
+        // The query string goes FIRST and unconditionally — `#/search?q=<what
+        // they typed>` is the single most likely way user text would arrive here.
+        .replace(/\?.*$/, "")
+        .replace(/^\/?#/, "")
+        .replace(/^\/+|\/+$/g, ""));
+}
+/**
+ * How long a gap between two views before the second one starts a new session.
+ *
+ * 30 minutes is the web-analytics convention and it is the right one here for a
+ * reason specific to this fleet: the owner leaves tabs open for days. Without a
+ * gap rule, "session length" would be measured in hours of an idle laptop and
+ * every engagement number would be fiction.
+ */
+export const SESSION_GAP_MS = 30 * 60 * 1000;
+/**
+ * The largest slice of time a single view may contribute to `activeMs`.
+ *
+ * Dwell is measured BETWEEN beacons, so the last view before someone walks away
+ * has no successor to bound it — and the next beacon, whenever it comes, would
+ * otherwise donate the whole absence to the previous page. Capping each slice
+ * means an abandoned tab contributes one cap's worth and stops, which
+ * under-reports a long genuine read and cannot over-report an empty room. That
+ * is the correct direction for a signal whose job is to say what holds
+ * interest: over-reporting attention nobody paid is the failure that matters.
+ */
+export const MAX_DWELL_SLICE_MS = 5 * 60 * 1000;
+/**
+ * Fold one view into a user's history.
+ *
+ * `lastTs` is the previous view's timestamp for this USER (across places, not
+ * per place) — dwell is time spent on the page you were already on, so the
+ * credit goes backwards. A null `lastTs` is a first-ever view: a new session
+ * that credits nothing, because there is no earlier page to have been reading.
+ *
+ * Clock skew is handled by clamping rather than by trusting: a `ts` at or
+ * before `lastTs` yields zero dwell. A device with a wrong clock should make a
+ * number boring, never negative.
+ */
+export function foldView(lastTs, ts) {
+    if (lastTs === null)
+        return { newSession: true, activeMs: 0 };
+    const gap = ts - lastTs;
+    if (gap <= 0)
+        return { newSession: false, activeMs: 0 };
+    if (gap >= SESSION_GAP_MS)
+        return { newSession: true, activeMs: 0 };
+    return { newSession: false, activeMs: Math.min(gap, MAX_DWELL_SLICE_MS) };
+}
+/** `2026-08-14` for a timestamp, in UTC. The day bucket every row is keyed on. */
+export function dayKey(ts) {
+    return new Date(ts).toISOString().slice(0, 10);
+}
+/** How many whole days ago `ts` was, relative to `now`. */
+export function daysSince(ts, now) {
+    return Math.max(0, Math.floor((now - ts) / 86_400_000));
+}
+export const INTEREST_ACTIVE_DAYS = 7;
+export const INTEREST_FADING_DAYS = 30;
+/**
+ * Classify one (user, app) pair.
+ *
+ * `sessions` distinguishes the two ways of not coming back, and they mean
+ * different things: someone who used an app for a month and stopped
+ * (`dropped`) is a feature that stopped delivering, where someone who opened it
+ * once and never returned (`bounced`) is a first impression that failed. One
+ * bucket for both would hide whichever is rarer.
+ */
+export function classifyInterest(input, now) {
+    if (input.lastSeenTs === null)
+        return "never";
+    const age = daysSince(input.lastSeenTs, now);
+    if (age < INTEREST_ACTIVE_DAYS)
+        return "active";
+    if (age < INTEREST_FADING_DAYS)
+        return "fading";
+    return input.sessions <= 1 ? "bounced" : "dropped";
+}

package/dist/server/engagement/store.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The per-app ENGAGEMENT database — who opens which places, how often, and when
+ * they stopped.
+ *
+ * ── Its own file, beside `metrics.sqlite`, on purpose ───────────────────────
+ * `metrics/store.ts` opens with a promise: no user id, no query string, no
+ * path, in twelve apps including the zero-knowledge vault. That promise is the
+ * reason its middleware is safe to run everywhere, and a user-keyed table added
+ * to that file would retire it silently. So this is `engagement.sqlite`: a
+ * different file, a different guarantee, and an app that has never mounted the
+ * recorder simply has no such file at all.
+ *
+ * ── AGGREGATED, never an event log ──────────────────────────────────────────
+ * One row per (user, place, UTC day). The alternative — a row per view — buys
+ * nothing at this fleet's size and costs the one thing worth protecting: an
+ * event log is a timeline, and a timeline of a household's private apps is a
+ * far more sensitive object than a count. Sequence is exactly the information
+ * we do not want to be holding, so the schema cannot express it.
+ *
+ * The one place ordering DOES matter is sessionization, and it is resolved at
+ * WRITE time against `engagement_users.last_ts` — a single stored clock per
+ * user, which survives a restart and reveals nothing on its own. See
+ * `policy.ts:foldView`.
+ *
+ * ── Bounded like the rest of the telemetry ──────────────────────────────────
+ * Daily rows are trimmed by AGE, because the question this table answers ("is
+ * anyone still using it?") is a question about recent history, and a return
+ * curve longer than a quarter is not something a three-person fleet can read.
+ * The per-user roll-up is NOT trimmed by age: it is one row per (user, place)
+ * pair carrying first/last seen, and it is precisely the row that must survive
+ * for "dropped off" to be answerable. Dropping it after 90 days would make
+ * every lapsed user look like a new one.
+ */
+import { Database } from "bun:sqlite";
+import type { EngagementDay, EngagementUser, EngagementUserPlace } from "./types.js";
+export type { EngagementDay, EngagementUser, EngagementUserPlace } from "./types.js";
+/** How much history the daily grain keeps. */
+export declare const ENGAGEMENT_DAY_RETENTION_DAYS = 120;
+export interface EngagementStoreOptions {
+    dbPath: string;
+    retentionDays?: number;
+}
+export declare class EngagementStore {
+    readonly handle: Database;
+    readonly retentionDays: number;
+    private writes;
+    constructor(options: EngagementStoreOptions);
+    private migrate;
+    /**
+     * Record one resolved place-view.
+     *
+     * `place` must ALREADY have been through `resolvePlace` — this method does not
+     * validate it, because the allowlist lives with the app that owns the route
+     * manifest and a second half-check here would be the one somebody trusts. The
+     * HTTP door (`api.ts`) is where resolution happens, and `engagement.test.ts`
+     * pins that it does.
+     *
+     * Returns the fold that was applied, so a caller (or a test) can assert on
+     * the sessionization rather than re-deriving it.
+     */
+    recordView(input: {
+        userKey: string;
+        place: string;
+        ts: number;
+    }): {
+        newSession: boolean;
+        activeMs: number;
+    };
+    /** Every account's roll-up for this app, most recently seen first. */
+    users(): EngagementUser[];
+    /** Every (user, place) roll-up — the per-FEATURE grain, whole-fleet readable. */
+    places(): EngagementUserPlace[];
+    /** Daily buckets inside a window — the sessions-over-time and return curve. */
+    days(sinceTs: number): EngagementDay[];
+    /**
+     * Drop daily rows older than the retention window.
+     *
+     * 🔴 Only `engagement_days`. The two roll-ups are deliberately untouched —
+     * see the file header. An agent "completing" this by trimming them too would
+     * delete the only record that somebody used to be here, which is the entire
+     * drop-off signal.
+     */
+    prune(at?: number): number;
+    /** Row counts + age bounds, for the retention card. */
+    stats(): {
+        days: number;
+        places: number;
+        users: number;
+        oldestDay: string | null;
+    };
+    close(): void;
+}

package/dist/server/engagement/store.js

@@ -0,0 +1,223 @@
+/**
+ * The per-app ENGAGEMENT database — who opens which places, how often, and when
+ * they stopped.
+ *
+ * ── Its own file, beside `metrics.sqlite`, on purpose ───────────────────────
+ * `metrics/store.ts` opens with a promise: no user id, no query string, no
+ * path, in twelve apps including the zero-knowledge vault. That promise is the
+ * reason its middleware is safe to run everywhere, and a user-keyed table added
+ * to that file would retire it silently. So this is `engagement.sqlite`: a
+ * different file, a different guarantee, and an app that has never mounted the
+ * recorder simply has no such file at all.
+ *
+ * ── AGGREGATED, never an event log ──────────────────────────────────────────
+ * One row per (user, place, UTC day). The alternative — a row per view — buys
+ * nothing at this fleet's size and costs the one thing worth protecting: an
+ * event log is a timeline, and a timeline of a household's private apps is a
+ * far more sensitive object than a count. Sequence is exactly the information
+ * we do not want to be holding, so the schema cannot express it.
+ *
+ * The one place ordering DOES matter is sessionization, and it is resolved at
+ * WRITE time against `engagement_users.last_ts` — a single stored clock per
+ * user, which survives a restart and reveals nothing on its own. See
+ * `policy.ts:foldView`.
+ *
+ * ── Bounded like the rest of the telemetry ──────────────────────────────────
+ * Daily rows are trimmed by AGE, because the question this table answers ("is
+ * anyone still using it?") is a question about recent history, and a return
+ * curve longer than a quarter is not something a three-person fleet can read.
+ * The per-user roll-up is NOT trimmed by age: it is one row per (user, place)
+ * pair carrying first/last seen, and it is precisely the row that must survive
+ * for "dropped off" to be answerable. Dropping it after 90 days would make
+ * every lapsed user look like a new one.
+ */
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { dayKey, foldView } from "./policy.js";
+/**
+ * `bun:sqlite`'s `create: true` creates the FILE, never the directory above it, so a first boot
+ * into an empty data dir would throw here. Swallowed on purpose: the open that follows names the
+ * real problem, and telemetry must never be what takes an app's boot down.
+ */
+function ensureDbDirectory(dbPath) {
+    if (!dbPath || dbPath === ":memory:" || dbPath.startsWith("file::memory:"))
+        return;
+    try {
+        mkdirSync(dirname(resolve(dbPath)), { recursive: true });
+    }
+    catch {
+        // see above
+    }
+}
+/** How much history the daily grain keeps. */
+export const ENGAGEMENT_DAY_RETENTION_DAYS = 120;
+export class EngagementStore {
+    handle;
+    retentionDays;
+    writes = 0;
+    constructor(options) {
+        this.retentionDays = options.retentionDays ?? ENGAGEMENT_DAY_RETENTION_DAYS;
+        // `create: true` creates the file, never the directory above it — see
+        // `ensureDbDirectory`, which is the whole of notes' "NOT YET DIAGNOSED" waiver.
+        ensureDbDirectory(options.dbPath);
+        this.handle = new Database(options.dbPath, { create: true });
+        // busy_timeout FIRST — journal_mode takes a lock. scripts/sqliteBusyTimeout.test.ts
+        this.handle.run("PRAGMA busy_timeout = 5000");
+        this.handle.run("PRAGMA journal_mode = WAL");
+        // A beacon must never block a page on an fsync, and losing the last few
+        // views to a hard kill costs nothing a human would notice.
+        this.handle.run("PRAGMA synchronous = NORMAL");
+        this.migrate();
+    }
+    migrate() {
+        this.handle.run(`CREATE TABLE IF NOT EXISTS engagement_days (
+			user_key TEXT NOT NULL,
+			place TEXT NOT NULL,
+			day TEXT NOT NULL,
+			views INTEGER NOT NULL DEFAULT 0,
+			active_ms INTEGER NOT NULL DEFAULT 0,
+			sessions INTEGER NOT NULL DEFAULT 0,
+			first_ts INTEGER NOT NULL,
+			last_ts INTEGER NOT NULL,
+			PRIMARY KEY (user_key, place, day)
+		)`);
+        this.handle.run("CREATE INDEX IF NOT EXISTS idx_engagement_days_day ON engagement_days (day)");
+        // The (user, place) lifetime row. Separate from the daily grain because it
+        // must OUTLIVE it — see the header: this is the row that knows somebody
+        // stopped, and age-trimming it would turn every lapsed account into a new
+        // one on day 121.
+        this.handle.run(`CREATE TABLE IF NOT EXISTS engagement_places (
+			user_key TEXT NOT NULL,
+			place TEXT NOT NULL,
+			views INTEGER NOT NULL DEFAULT 0,
+			sessions INTEGER NOT NULL DEFAULT 0,
+			active_ms INTEGER NOT NULL DEFAULT 0,
+			first_ts INTEGER NOT NULL,
+			last_ts INTEGER NOT NULL,
+			PRIMARY KEY (user_key, place)
+		)`);
+        this.handle.run("CREATE INDEX IF NOT EXISTS idx_engagement_places_last ON engagement_places (last_ts)");
+        // One row per ACCOUNT. `last_ts` here is the sessionization clock — the only
+        // piece of ordering the schema keeps, and it keeps exactly one timestamp
+        // rather than a sequence (header, "AGGREGATED, never an event log").
+        this.handle.run(`CREATE TABLE IF NOT EXISTS engagement_users (
+			user_key TEXT PRIMARY KEY,
+			views INTEGER NOT NULL DEFAULT 0,
+			sessions INTEGER NOT NULL DEFAULT 0,
+			active_ms INTEGER NOT NULL DEFAULT 0,
+			first_ts INTEGER NOT NULL,
+			last_ts INTEGER NOT NULL,
+			last_place TEXT NOT NULL DEFAULT ''
+		)`);
+    }
+    /**
+     * Record one resolved place-view.
+     *
+     * `place` must ALREADY have been through `resolvePlace` — this method does not
+     * validate it, because the allowlist lives with the app that owns the route
+     * manifest and a second half-check here would be the one somebody trusts. The
+     * HTTP door (`api.ts`) is where resolution happens, and `engagement.test.ts`
+     * pins that it does.
+     *
+     * Returns the fold that was applied, so a caller (or a test) can assert on
+     * the sessionization rather than re-deriving it.
+     */
+    recordView(input) {
+        const { userKey, place, ts } = input;
+        const prior = this.handle
+            .query("SELECT last_ts, last_place FROM engagement_users WHERE user_key = ?")
+            .get(userKey);
+        const fold = foldView(prior ? prior.last_ts : null, ts);
+        // Dwell is credited BACKWARDS, to the page they were already on — which is
+        // why `last_place` is stored at all. Crediting it to the page just opened
+        // would mean the most-abandoned page in the app scored highest.
+        if (fold.activeMs > 0 && prior?.last_place) {
+            const creditDay = dayKey(prior.last_ts);
+            this.handle.run("UPDATE engagement_days SET active_ms = active_ms + ? WHERE user_key = ? AND place = ? AND day = ?", [fold.activeMs, userKey, prior.last_place, creditDay]);
+            this.handle.run("UPDATE engagement_places SET active_ms = active_ms + ? WHERE user_key = ? AND place = ?", [fold.activeMs, userKey, prior.last_place]);
+        }
+        const sessionDelta = fold.newSession ? 1 : 0;
+        this.handle.run(`INSERT INTO engagement_days (user_key, place, day, views, active_ms, sessions, first_ts, last_ts)
+			 VALUES (?, ?, ?, 1, 0, ?, ?, ?)
+			 ON CONFLICT(user_key, place, day) DO UPDATE SET
+			   views = views + 1,
+			   sessions = sessions + excluded.sessions,
+			   last_ts = excluded.last_ts`, [userKey, place, dayKey(ts), sessionDelta, ts, ts]);
+        this.handle.run(`INSERT INTO engagement_places (user_key, place, views, sessions, active_ms, first_ts, last_ts)
+			 VALUES (?, ?, 1, ?, 0, ?, ?)
+			 ON CONFLICT(user_key, place) DO UPDATE SET
+			   views = views + 1,
+			   sessions = sessions + excluded.sessions,
+			   last_ts = excluded.last_ts`, [userKey, place, sessionDelta, ts, ts]);
+        this.handle.run(`INSERT INTO engagement_users (user_key, views, sessions, active_ms, first_ts, last_ts, last_place)
+			 VALUES (?, 1, ?, 0, ?, ?, ?)
+			 ON CONFLICT(user_key) DO UPDATE SET
+			   views = views + 1,
+			   sessions = sessions + excluded.sessions,
+			   active_ms = active_ms + ?,
+			   last_ts = excluded.last_ts,
+			   last_place = excluded.last_place`, [userKey, sessionDelta, ts, ts, place, fold.activeMs]);
+        // Amortised, exactly as the metrics store trims: a DELETE per beacon would
+        // cost more than the beacon, and never trimming lets a long-lived daemon
+        // keep every day it has ever served.
+        if (++this.writes % 256 === 0)
+            this.prune(ts);
+        return fold;
+    }
+    /** Every account's roll-up for this app, most recently seen first. */
+    users() {
+        return this.handle
+            .query(`SELECT u.user_key AS userKey, u.views AS views, u.sessions AS sessions,
+				        u.active_ms AS activeMs, u.first_ts AS firstTs, u.last_ts AS lastTs,
+				        (SELECT COUNT(*) FROM engagement_places p WHERE p.user_key = u.user_key) AS places
+				   FROM engagement_users u
+				  ORDER BY u.last_ts DESC`)
+            .all();
+    }
+    /** Every (user, place) roll-up — the per-FEATURE grain, whole-fleet readable. */
+    places() {
+        return this.handle
+            .query(`SELECT user_key AS userKey, place, views, sessions, active_ms AS activeMs,
+				        first_ts AS firstTs, last_ts AS lastTs
+				   FROM engagement_places
+				  ORDER BY views DESC`)
+            .all();
+    }
+    /** Daily buckets inside a window — the sessions-over-time and return curve. */
+    days(sinceTs) {
+        return this.handle
+            .query(`SELECT user_key AS userKey, place, day, views, active_ms AS activeMs, sessions
+				   FROM engagement_days WHERE day >= ?
+				  ORDER BY day ASC`)
+            .all(dayKey(sinceTs));
+    }
+    /**
+     * Drop daily rows older than the retention window.
+     *
+     * 🔴 Only `engagement_days`. The two roll-ups are deliberately untouched —
+     * see the file header. An agent "completing" this by trimming them too would
+     * delete the only record that somebody used to be here, which is the entire
+     * drop-off signal.
+     */
+    prune(at = Date.now()) {
+        const cutoff = dayKey(at - this.retentionDays * 86_400_000);
+        return this.handle.run("DELETE FROM engagement_days WHERE day < ?", [cutoff]).changes;
+    }
+    /** Row counts + age bounds, for the retention card. */
+    stats() {
+        const n = (sql) => (this.handle.query(sql).get()?.n ?? 0);
+        const oldest = this.handle
+            .query("SELECT MIN(day) AS d FROM engagement_days")
+            .get();
+        return {
+            days: n("SELECT COUNT(*) AS n FROM engagement_days"),
+            places: n("SELECT COUNT(*) AS n FROM engagement_places"),
+            users: n("SELECT COUNT(*) AS n FROM engagement_users"),
+            oldestDay: oldest?.d ?? null,
+        };
+    }
+    close() {
+        this.handle.close();
+    }
+}

package/dist/server/engagement/summary.d.ts

@@ -0,0 +1,102 @@
+/**
+ * One app's engagement, folded into the shape the console draws.
+ *
+ * ── Why the APP does the folding ────────────────────────────────────────────
+ * The same argument `metrics/inventory.ts` makes: the console runs on this Mac
+ * and most of the fleet runs on a checkout-less box reachable only over HTTPS,
+ * so the app that owns the data is the only thing that can read it. Shipping
+ * raw daily rows would also mean shipping the per-day timeline of a household's
+ * private apps across the wire on every poll, when the console draws totals.
+ *
+ * ── Everything here is pure over rows ───────────────────────────────────────
+ * `summarize` takes the three roll-ups and a clock, so `engagement.test.ts`
+ * drives it with hand-written rows and checks arithmetic a human can verify —
+ * which is the whole design constraint at n = 3. No I/O, no `Date.now()`.
+ */
+import { type EngagementDay, type EngagementUser, type EngagementUserPlace, type InterestVerdict } from "./types.js";
+/** One account's relationship with one app. */
+export interface UserEngagement {
+    userKey: string;
+    views: number;
+    sessions: number;
+    activeMs: number;
+    firstTs: number;
+    lastTs: number;
+    /** Distinct places this account has opened here. */
+    places: number;
+    interest: InterestVerdict;
+    /** Whole days since this account was last seen in this app. */
+    daysSinceSeen: number;
+}
+/** One PLACE inside an app, across every account — the per-feature grain. */
+export interface PlaceEngagement {
+    place: string;
+    /** Distinct accounts that have ever opened it. */
+    users: number;
+    views: number;
+    sessions: number;
+    activeMs: number;
+    lastTs: number;
+    /** Mean ms of attention per view. The "does it hold interest" number. */
+    msPerView: number;
+}
+/** One day of the app's whole activity. */
+export interface DailyEngagement {
+    day: string;
+    views: number;
+    sessions: number;
+    /** Distinct accounts active that day. */
+    users: number;
+}
+export interface AppEngagement {
+    app: string;
+    generatedAt: number;
+    users: UserEngagement[];
+    places: PlaceEngagement[];
+    /** The (user, place) cross grain — what lets the console answer "which
+     *  features does THIS person like", rather than only the two margins. */
+    userPlaces: Array<{
+        userKey: string;
+        place: string;
+        views: number;
+        activeMs: number;
+        lastTs: number;
+    }>;
+    daily: DailyEngagement[];
+    totals: {
+        users: number;
+        views: number;
+        sessions: number;
+        activeMs: number;
+        /** Accounts with more than one session — they came back. */
+        returning: number;
+        /** Accounts with exactly one session, ever. */
+        oneTime: number;
+        /** Accounts seen in the last week. */
+        activeUsers: number;
+    };
+}
+export interface SummarizeInput {
+    app: string;
+    now: number;
+    users: EngagementUser[];
+    places: EngagementUserPlace[];
+    days: EngagementDay[];
+}
+export declare function summarize(input: SummarizeInput): AppEngagement;
+/**
+ * The return curve: of the accounts first seen on a given day, how many came
+ * back at least once afterwards.
+ *
+ * Stated as WHOLE ACCOUNTS on a named cohort day rather than as a percentage,
+ * because a percentage of one person is a number that lies confidently. The
+ * console renders "2 of 3 came back" for the same reason.
+ */
+export declare function returnCurve(users: Array<{
+    firstTs: number;
+    sessions: number;
+}>, now: number, windowDays?: number): Array<{
+    day: string;
+    joined: number;
+    returned: number;
+}>;