cursedbelt-server 4.18.1 → 4.19.0

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;
+}>;

package/dist/server/engagement/summary.js

@@ -0,0 +1,127 @@
+/**
+ * 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 { classifyInterest, dayKey, } from "./types.js";
+export function summarize(input) {
+    const { app, now } = input;
+    const users = input.users.map((u) => ({
+        userKey: u.userKey,
+        views: u.views,
+        sessions: u.sessions,
+        activeMs: u.activeMs,
+        firstTs: u.firstTs,
+        lastTs: u.lastTs,
+        places: u.places,
+        interest: classifyInterest({ lastSeenTs: u.lastTs, sessions: u.sessions }, now),
+        daysSinceSeen: Math.max(0, Math.floor((now - u.lastTs) / 86_400_000)),
+    }));
+    // Fold the (user, place) rows down the USER axis to get the per-feature view.
+    const byPlace = new Map();
+    for (const row of input.places) {
+        const existing = byPlace.get(row.place);
+        if (existing) {
+            existing.users += 1;
+            existing.views += row.views;
+            existing.sessions += row.sessions;
+            existing.activeMs += row.activeMs;
+            existing.lastTs = Math.max(existing.lastTs, row.lastTs);
+        }
+        else {
+            byPlace.set(row.place, {
+                place: row.place,
+                users: 1,
+                views: row.views,
+                sessions: row.sessions,
+                activeMs: row.activeMs,
+                lastTs: row.lastTs,
+                msPerView: 0,
+            });
+        }
+    }
+    const places = [...byPlace.values()].map((p) => ({
+        ...p,
+        // Integer ms: a mean over three people does not deserve decimals, and a
+        // whole number is one the owner can sanity-check against a stopwatch.
+        msPerView: p.views > 0 ? Math.round(p.activeMs / p.views) : 0,
+    }));
+    places.sort((a, b) => b.views - a.views || a.place.localeCompare(b.place));
+    // Distinct users per day needs the (user, place, day) grain, which is exactly
+    // why `days()` returns it rather than pre-summed days.
+    const dayAcc = new Map();
+    for (const row of input.days) {
+        let bucket = dayAcc.get(row.day);
+        if (!bucket) {
+            bucket = { views: 0, sessions: 0, users: new Set() };
+            dayAcc.set(row.day, bucket);
+        }
+        bucket.views += row.views;
+        bucket.sessions += row.sessions;
+        bucket.users.add(row.userKey);
+    }
+    const daily = [...dayAcc.entries()]
+        .map(([day, b]) => ({ day, views: b.views, sessions: b.sessions, users: b.users.size }))
+        .sort((a, b) => a.day.localeCompare(b.day));
+    const userPlaces = input.places
+        .map((p) => ({
+        userKey: p.userKey,
+        place: p.place,
+        views: p.views,
+        activeMs: p.activeMs,
+        lastTs: p.lastTs,
+    }))
+        .sort((a, b) => b.views - a.views);
+    return {
+        app,
+        generatedAt: now,
+        users,
+        places,
+        userPlaces,
+        daily,
+        totals: {
+            users: users.length,
+            views: users.reduce((n, u) => n + u.views, 0),
+            sessions: users.reduce((n, u) => n + u.sessions, 0),
+            activeMs: users.reduce((n, u) => n + u.activeMs, 0),
+            returning: users.filter((u) => u.sessions > 1).length,
+            oneTime: users.filter((u) => u.sessions <= 1).length,
+            activeUsers: users.filter((u) => u.interest === "active").length,
+        },
+    };
+}
+/**
+ * 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 function returnCurve(users, now, windowDays = 30) {
+    const cutoff = now - windowDays * 86_400_000;
+    const acc = new Map();
+    for (const u of users) {
+        if (u.firstTs < cutoff)
+            continue;
+        const day = dayKey(u.firstTs);
+        const bucket = acc.get(day) ?? { joined: 0, returned: 0 };
+        bucket.joined += 1;
+        if (u.sessions > 1)
+            bucket.returned += 1;
+        acc.set(day, bucket);
+    }
+    return [...acc.entries()]
+        .map(([day, b]) => ({ day, ...b }))
+        .sort((a, b) => a.day.localeCompare(b.day));
+}

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

@@ -0,0 +1,42 @@
+/**
+ * The row shapes the engagement store reads and writes, plus the pure policy
+ * re-exported through one door.
+ *
+ * Split out of `store.ts` so `summary.ts` — and the console's BROWSER code,
+ * which types the fetched payload — can import them without pulling in
+ * `bun:sqlite`. A type-only import would be erased, but the console also wants
+ * `classifyInterest` and `dayKey` at runtime to label a row it is rendering,
+ * and importing those from the store module would drag a native sqlite binding
+ * into a Vite build.
+ */
+export { classifyInterest, dayKey, daysSince, ENGAGEMENT_EXCLUDED_APPS, engagementAllowedForApp, foldView, INTEREST_ACTIVE_DAYS, INTEREST_FADING_DAYS, type InterestVerdict, MAX_DWELL_SLICE_MS, normalizePlaceId, OTHER_PLACE, resolvePlace, SESSION_GAP_MS, type ViewFold, } from "./policy.js";
+/** One (user, place, UTC day) bucket. */
+export interface EngagementDay {
+    userKey: string;
+    place: string;
+    day: string;
+    views: number;
+    activeMs: number;
+    sessions: number;
+}
+/** One (user, place) lifetime roll-up — what the retention answers read. */
+export interface EngagementUserPlace {
+    userKey: string;
+    place: string;
+    views: number;
+    sessions: number;
+    activeMs: number;
+    firstTs: number;
+    lastTs: number;
+}
+/** One account's relationship with the whole app. */
+export interface EngagementUser {
+    userKey: string;
+    views: number;
+    sessions: number;
+    activeMs: number;
+    firstTs: number;
+    lastTs: number;
+    /** Distinct places this account has ever opened in this app. */
+    places: number;
+}

package/dist/server/engagement/types.js

@@ -0,0 +1,12 @@
+/**
+ * The row shapes the engagement store reads and writes, plus the pure policy
+ * re-exported through one door.
+ *
+ * Split out of `store.ts` so `summary.ts` — and the console's BROWSER code,
+ * which types the fetched payload — can import them without pulling in
+ * `bun:sqlite`. A type-only import would be erased, but the console also wants
+ * `classifyInterest` and `dayKey` at runtime to label a row it is rendering,
+ * and importing those from the store module would drag a native sqlite binding
+ * into a Vite build.
+ */
+export { classifyInterest, dayKey, daysSince, ENGAGEMENT_EXCLUDED_APPS, engagementAllowedForApp, foldView, INTEREST_ACTIVE_DAYS, INTEREST_FADING_DAYS, MAX_DWELL_SLICE_MS, normalizePlaceId, OTHER_PLACE, resolvePlace, SESSION_GAP_MS, } from "./policy.js";