cursedbelt-server 4.18.1 → 4.19.0

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

@@ -0,0 +1,18 @@
+export interface EngagementEnv {
+    enabled: boolean;
+    /** Absolute path of the engagement database, or null when disabled. */
+    dbPath: string | null;
+    /** Why it is off, when it is — surfaced in the app-info overlay. */
+    reason: string | null;
+}
+export interface EngagementEnvOptions {
+    /**
+     * Where this app keeps its data — the app's own resolver, because WHERE an app's data
+     * lives is the app's decision, not this library's. It may THROW when there is no honest
+     * answer (a test runner, an unset state root); that turns recording off rather than
+     * guessing. Defaults to `cursedbelt-server/satellite-config`'s `resolveAppDataDir` — the same
+     * call every app's copy made — so `engagement.sqlite` sits beside the app's own database.
+     */
+    dataDir?: (app: string, env: NodeJS.ProcessEnv) => string;
+}
+export declare function readEngagementEnv(app: string, env?: NodeJS.ProcessEnv, options?: EngagementEnvOptions): EngagementEnv;

package/dist/server/engagement/env.js

@@ -0,0 +1,52 @@
+/**
+ * Whether a satellite records engagement — read from the environment in one
+ * place, mirroring `metrics/env.ts` so the two are read the same way.
+ *
+ * ── The rules, and where they differ from metrics ───────────────────────────
+ * 1. **A test runner is never metered.** Same reason as metrics: constructing a
+ *    store in a suite that named no data directory would throw and take the
+ *    app's whole suite with it.
+ * 2. **Recording only — there is no read surface to configure.** The shared
+ *    `SATELLITE_METRICS_TOKEN` bearer that once unlocked `/api/admin/engagement`
+ *    is gone, and with it the route (`api.ts` says why). An app keeps its own
+ *    history; a reader on this Mac opens `engagement.sqlite` directly.
+ * 3. 🔴 **An excluded app is off no matter what the environment says.** This is
+ *    the one that is NOT a mirror of metrics. `engagementAllowedForApp` is
+ *    consulted first and cannot be overridden by an env var, because the vault's
+ *    exclusion must not be one `SATELLITE_ENGAGEMENT=1` away from being undone
+ *    on a box nobody is looking at.
+ * 4. **`SATELLITE_ENGAGEMENT=0` turns it off** for an app that is otherwise
+ *    allowed. One escape hatch, in the safe direction only.
+ */
+import { join } from "node:path";
+import { isTestRuntime } from "../satellite/door.js";
+import { resolveAppDataDir } from "../satellite/config.js";
+import { engagementAllowedForApp } from "./policy.js";
+const appDataDir = (app, env) => resolveAppDataDir({ app, env });
+export function readEngagementEnv(app, env = process.env, options = {}) {
+    const off = (reason) => ({
+        enabled: false,
+        dbPath: null,
+        reason,
+    });
+    // Rule 3 first, deliberately: no later branch can turn this back on.
+    if (!engagementAllowedForApp(app))
+        return off(`${app} is excluded from engagement by the kit`);
+    if (env.SATELLITE_ENGAGEMENT === "0")
+        return off("SATELLITE_ENGAGEMENT=0");
+    if (isTestRuntime(env))
+        return off("test runtime");
+    try {
+        return {
+            enabled: true,
+            dbPath: join((options.dataDir ?? appDataDir)(app, env), "engagement.sqlite"),
+            reason: null,
+        };
+    }
+    catch {
+        // The resolver refuses rather than guessing where data belongs.
+        // "Then don't" is the right answer for telemetry — the app boots, it
+        // simply has no history.
+        return off("no resolvable data directory");
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * `cursedbelt-server/engagement` — the SERVER half of the fleet's product analytics: the
+ * recorder, the store, the policy and the summary. Bun-only (`bun:sqlite`).
+ *
+ * ── Why it is here, since 4.19.0 (task 280) ─────────────────────────────────
+ * It was `src/kit/engagement/` copied whole into `roms`, `family`, `music` and `collections`.
+ * `policy.ts` holds the three privacy rules that make it safe to run USER-KEYED analytics
+ * inside private household apps, and four copies of a privacy promise is four promises, with
+ * nothing keeping them the same — three of the twelve files had already forked (in `music`,
+ * doc comments only; the behaviour was identical in all four, so the plurality's text is what
+ * came across). The browser half — the beacon — is React and lives in the design system's tier;
+ * it depends on nothing here but the wire shape `POST <mount>/view {place}`.
+ *
+ * The split it depends on:
+ *
+ *   metrics/      "is the fleet healthy" — throughput, latency, status codes. Promises it
+ *                 holds NO user id, in every app.
+ *   engagement/   "is anyone using it, who, and what do they like" — per user, per app,
+ *                 per PLACE, plus a drop-off signal. User-keyed by definition, which is why
+ *                 it is a different store (`engagement.sqlite`).
+ *
+ * Read `policy.ts` before changing anything: the three rules (allowlisted places, apps
+ * excluded by name, counts-and-clocks only) are structural, not conventions.
+ *
+ * ── 🔴 Mount order: AFTER the session gate (`docs/engagement.md`) ─────────────
+ * The recorder has no credential of its own; the user key comes ONLY from the app's
+ * `resolveUser(c)`, which needs the gate to have run. That is the mirror image of a sync
+ * receiver, which carries its own bearer and must mount BEFORE the gate.
+ *
+ * ── 🔴 What stays in the app ────────────────────────────────────────────────
+ * `routes.manifest.json` and the test that proves it parses. `engagementPlacesFor` returns
+ * `[]` for anything it cannot read — silently, by design, so telemetry never takes a boot
+ * down — which degrades the allowlist to nothing while the board goes on rendering. Only the
+ * app can prove its own manifest parses; `apps/roms/routes.manifest.test.ts` is the pattern.
+ *
+ * ```ts
+ * import { createEngagementRecorder, EngagementStore, engagementPlacesFor, readEngagementEnv }
+ *   from "cursedbelt-server/engagement";
+ *
+ * const setting = readEngagementEnv("myapp");   // beside the app's own data, or off
+ * if (setting.enabled && setting.dbPath) {
+ *   const store = new EngagementStore({ dbPath: setting.dbPath });
+ *   app.route("/api/engagement", createEngagementRecorder({
+ *     store, app: "myapp", places: engagementPlacesFor(import.meta.dir),
+ *     resolveUser: (c) => c.get("user")?.id ?? null,
+ *   }));
+ * }
+ * ```
+ */
+export { type AppEngagementSnapshot, createEngagementRecorder, type EngagementApiOptions, readAppEngagement, } from "./api.js";
+export { type EngagementEnv, type EngagementEnvOptions, readEngagementEnv } from "./env.js";
+export { type EngagementPlace, engagementPlacesFor } from "./places.js";
+export { classifyInterest, dayKey, daysSince, ENGAGEMENT_EXCLUDED_APPS, engagementAllowedForApp, foldView, INTEREST_ACTIVE_DAYS, INTEREST_FADING_DAYS, type InterestVerdict, MAX_DWELL_SLICE_MS, normalizePlaceId, OTHER_PLACE, type PlaceRef, resolvePlace, SESSION_GAP_MS, type ViewFold, } from "./policy.js";
+export { ENGAGEMENT_DAY_RETENTION_DAYS, type EngagementDay, EngagementStore, type EngagementStoreOptions, type EngagementUser, type EngagementUserPlace, } from "./store.js";
+export { type AppEngagement, type DailyEngagement, type PlaceEngagement, returnCurve, summarize, type SummarizeInput, type UserEngagement, } from "./summary.js";

package/dist/server/engagement/index.js

@@ -0,0 +1,55 @@
+/**
+ * `cursedbelt-server/engagement` — the SERVER half of the fleet's product analytics: the
+ * recorder, the store, the policy and the summary. Bun-only (`bun:sqlite`).
+ *
+ * ── Why it is here, since 4.19.0 (task 280) ─────────────────────────────────
+ * It was `src/kit/engagement/` copied whole into `roms`, `family`, `music` and `collections`.
+ * `policy.ts` holds the three privacy rules that make it safe to run USER-KEYED analytics
+ * inside private household apps, and four copies of a privacy promise is four promises, with
+ * nothing keeping them the same — three of the twelve files had already forked (in `music`,
+ * doc comments only; the behaviour was identical in all four, so the plurality's text is what
+ * came across). The browser half — the beacon — is React and lives in the design system's tier;
+ * it depends on nothing here but the wire shape `POST <mount>/view {place}`.
+ *
+ * The split it depends on:
+ *
+ *   metrics/      "is the fleet healthy" — throughput, latency, status codes. Promises it
+ *                 holds NO user id, in every app.
+ *   engagement/   "is anyone using it, who, and what do they like" — per user, per app,
+ *                 per PLACE, plus a drop-off signal. User-keyed by definition, which is why
+ *                 it is a different store (`engagement.sqlite`).
+ *
+ * Read `policy.ts` before changing anything: the three rules (allowlisted places, apps
+ * excluded by name, counts-and-clocks only) are structural, not conventions.
+ *
+ * ── 🔴 Mount order: AFTER the session gate (`docs/engagement.md`) ─────────────
+ * The recorder has no credential of its own; the user key comes ONLY from the app's
+ * `resolveUser(c)`, which needs the gate to have run. That is the mirror image of a sync
+ * receiver, which carries its own bearer and must mount BEFORE the gate.
+ *
+ * ── 🔴 What stays in the app ────────────────────────────────────────────────
+ * `routes.manifest.json` and the test that proves it parses. `engagementPlacesFor` returns
+ * `[]` for anything it cannot read — silently, by design, so telemetry never takes a boot
+ * down — which degrades the allowlist to nothing while the board goes on rendering. Only the
+ * app can prove its own manifest parses; `apps/roms/routes.manifest.test.ts` is the pattern.
+ *
+ * ```ts
+ * import { createEngagementRecorder, EngagementStore, engagementPlacesFor, readEngagementEnv }
+ *   from "cursedbelt-server/engagement";
+ *
+ * const setting = readEngagementEnv("myapp");   // beside the app's own data, or off
+ * if (setting.enabled && setting.dbPath) {
+ *   const store = new EngagementStore({ dbPath: setting.dbPath });
+ *   app.route("/api/engagement", createEngagementRecorder({
+ *     store, app: "myapp", places: engagementPlacesFor(import.meta.dir),
+ *     resolveUser: (c) => c.get("user")?.id ?? null,
+ *   }));
+ * }
+ * ```
+ */
+export { createEngagementRecorder, readAppEngagement, } from "./api.js";
+export { readEngagementEnv } from "./env.js";
+export { engagementPlacesFor } from "./places.js";
+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";
+export { ENGAGEMENT_DAY_RETENTION_DAYS, EngagementStore, } from "./store.js";
+export { returnCurve, summarize, } from "./summary.js";

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

@@ -0,0 +1,22 @@
+/**
+ * One declared page: the id the board shows, and the URL shape that reaches it.
+ *
+ * Both halves are needed because the browser knows a LOCATION and the board
+ * wants a NAME. Carrying the path here is what lets an app adopt the beacon
+ * without writing a second `route.view → place id` mapping per app — twelve
+ * such mappings would be twelve places for the two to drift, and a drifted one
+ * reads as a page nobody opens.
+ */
+export interface EngagementPlace {
+    id: string;
+    /** As the manifest states it — `/`, `/#/calendar`, `/#/t/:shelf`. */
+    path: string;
+}
+/**
+ * The declared places in `<dir>/routes.manifest.json`.
+ *
+ * `dir` is the app's own directory — pass `import.meta.dir` from `server.ts`,
+ * which is the source dir in dev and the artifact dir in production, and the
+ * manifest is copied into both.
+ */
+export declare function engagementPlacesFor(dir: string): EngagementPlace[];

package/dist/server/engagement/places.js

@@ -0,0 +1,63 @@
+/**
+ * An app's place allowlist, read from the `routes.manifest.json` it already
+ * maintains.
+ *
+ * ── Why the manifest and not a second list ─────────────────────────────────
+ * `routeManifest.ts` makes the argument already and it applies twice over
+ * here: "a hand-written list drifts, and its drift is SILENT in the direction
+ * that matters". For the route-health check the missing route is the untested
+ * one; for engagement the missing route is the page that reads as **unused**,
+ * which is worse — it is not a gap in the board, it is a wrong answer on it,
+ * and the wrong answer is one somebody deletes a feature over.
+ *
+ * The manifest is also already derived from whatever the app renders its
+ * navigation from, and it is already copied into the artifact by
+ * `buildSatelliteArtifact` — so this resolves on a checkout-less prod box as
+ * well as in a dev shell, with no new file to ship.
+ *
+ * ── Missing is EMPTY, never a throw ────────────────────────────────────────
+ * An app whose manifest cannot be found records everything as `other`, which
+ * is safe and visibly useless — the board shows one bucket and the owner asks
+ * why. A throw here would take the app's boot with it, and telemetry must
+ * never be able to do that (the same contract every installer in `server.ts`
+ * keeps).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Where the manifest sits, in a source tree and in a built artifact alike. */
+const MANIFEST = "routes.manifest.json";
+/**
+ * The declared places in `<dir>/routes.manifest.json`.
+ *
+ * `dir` is the app's own directory — pass `import.meta.dir` from `server.ts`,
+ * which is the source dir in dev and the artifact dir in production, and the
+ * manifest is copied into both.
+ */
+export function engagementPlacesFor(dir) {
+    const path = join(dir, MANIFEST);
+    if (!existsSync(path))
+        return [];
+    try {
+        const doc = JSON.parse(readFileSync(path, "utf8"));
+        const routes = Array.isArray(doc)
+            ? doc
+            : doc.routes;
+        if (!Array.isArray(routes))
+            return [];
+        const seen = new Set();
+        const places = [];
+        for (const raw of routes) {
+            const r = raw;
+            if (typeof r.id !== "string" || !r.id || seen.has(r.id))
+                continue;
+            seen.add(r.id);
+            places.push({ id: r.id, path: typeof r.path === "string" ? r.path : "" });
+        }
+        // Sorted so the allowlist a board renders is stable between deployments.
+        places.sort((a, b) => a.id.localeCompare(b.id));
+        return places;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,168 @@
+/**
+ * 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 declare 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 declare const ENGAGEMENT_EXCLUDED_APPS: readonly string[];
+/** Is this app allowed to record engagement at all? */
+export declare function engagementAllowedForApp(app: string): boolean;
+/** One declared page. Mirrors `places.ts`'s `EngagementPlace`. */
+export interface PlaceRef {
+    id: string;
+    /** As the route manifest states it — `/`, `/#/calendar`, `/#/t/:shelf`. */
+    path: string;
+}
+/**
+ * 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 declare function resolvePlace(claimed: string, allowed: readonly (string | PlaceRef)[]): string;
+/**
+ * `#/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 declare function normalizePlaceId(raw: string): string;
+/**
+ * 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 declare const SESSION_GAP_MS: number;
+/**
+ * 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 declare const MAX_DWELL_SLICE_MS: number;
+/** What one view adds to the running totals. */
+export interface ViewFold {
+    /** Does this view begin a new session? */
+    newSession: boolean;
+    /** Milliseconds of attention to credit to the PREVIOUS place. */
+    activeMs: number;
+}
+/**
+ * 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 declare function foldView(lastTs: number | null, ts: number): ViewFold;
+/** `2026-08-14` for a timestamp, in UTC. The day bucket every row is keyed on. */
+export declare function dayKey(ts: number): string;
+/** How many whole days ago `ts` was, relative to `now`. */
+export declare function daysSince(ts: number, now: number): number;
+/**
+ * How engaged an account is with an app right now.
+ *
+ * The owner asked for "what is holding and not holding interest", and half of
+ * that is the half that is easy to forget: an app nobody opens produces no
+ * rows, so it is invisible to every panel that draws what it finds. A verdict
+ * per (user, app) makes the absence a value.
+ *
+ * The thresholds are days, not rates, because at n = 3 a rate is noise. They
+ * are also deliberately generous — a fortnight away from the film library in
+ * August is not a lapsed user.
+ */
+export type InterestVerdict = 
+/** Seen in the last week. */
+"active"
+/** Seen in the last month, but not this week — cooling off. */
+ | "fading"
+/** Not seen in over a month, having used it more than once. Dropped off. */
+ | "dropped"
+/** Opened once, ever, and never came back. The clearest "did not hold". */
+ | "bounced"
+/** This account has never opened this app at all. */
+ | "never";
+export declare const INTEREST_ACTIVE_DAYS = 7;
+export declare 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 declare function classifyInterest(input: {
+    lastSeenTs: number | null;
+    sessions: number;
+}, now: number): InterestVerdict;

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