browser-broker 0.1.0

package/dist/src/operations/telemetry.js

@@ -0,0 +1,280 @@
+import { estimateTokens } from "../capture/tiers.js";
+import { clampLimit } from "./ledger.js";
+/**
+ * The capture telemetry rollups (`MILESTONES.md` #37, `SCHEMA.md` §1.7, §1.9).
+ *
+ * What pictures cost, and what diffs did — read back from the two tables that
+ * record it. This is the **reader** half of the measurement work. The study
+ * that compares one policy against another over real review work is a
+ * different thing and is not here (#37a): a study needs traffic to exist
+ * before it can be run, whereas these reads are what make the capture policy's
+ * effect legible at all, and they stand on their own the moment a single
+ * capture has been taken.
+ *
+ * ── The shape of these queries was decided by the indexes ────────────────
+ *
+ * This is worth stating plainly, because it is the constraint that chose every
+ * grouping below. `step-001-initial.ts` creates three indexes whose comments
+ * name this row's job before this row existed:
+ *
+ * | Index | Its own comment |
+ * |---|---|
+ * | `captures_taken_at (taken_at)` | "Listing, and the rollup." |
+ * | `comparisons_source (source_capture_id, at DESC)` | "The diffs run from one capture" |
+ * | `comparisons_target (target_capture_id)` | "and the diffs run against one — which is what tuning reads." |
+ *
+ * So a window over `taken_at` is an index range scan, and both directions of
+ * the diff question are single-key lookups. **A rollup that forced a full scan
+ * when an index for it existed would be the wrong shape**, and a rollup that
+ * needed an index that does not exist would be a reason to re-read the schema
+ * rather than to add one.
+ *
+ * The two groupings — `tier` and `kind` — are deliberately *not* indexed and
+ * are deliberately still here. Both are enum columns of three values each
+ * (§1.7), so grouping them is a pass over rows the window has already narrowed
+ * to, not a scan of the table. An index on a three-value column would be a
+ * write cost on every capture buying nothing a range scan does not already
+ * have.
+ *
+ * ── Read-only, and it does not sweep ────────────────────────────────────
+ *
+ * The same standing that `ledger.ts` claims and for the same reason: these
+ * decide nothing, grant nothing and refuse nothing, so they are not
+ * arbitration paths and are not entitled to expire anybody's lease (§5.2).
+ * Both tables record things that happened at a moment that has passed, so
+ * unlike `claims` there is nothing here to derive — a capture's size does not
+ * change because a lease lapsed.
+ *
+ * ── Estimated tokens are computed, never stored ─────────────────────────
+ *
+ * §1.7 deletes an `estimated_tokens` column on purpose and says why: it "is a
+ * calculation over two columns on the same row", and freezing it into a column
+ * would let it disagree with the dimensions beside it. The same section then
+ * requires it "appears on every capture response and **every rollup**". So it
+ * is computed here, by {@link estimateTokens}, from the dimensions the rows
+ * carry — one formula in `tiers.ts`, used by the capture path and by this
+ * reader, with no second copy to drift.
+ */
+/** The resolution rungs, exactly as the schema's check constraint spells them (§1.7). */
+export const CAPTURE_TIERS = ['default', 'detail', 'max'];
+/** The kinds of picture, exactly as the schema's check constraint spells them (§1.7). */
+export const CAPTURE_KINDS = ['viewport', 'element', 'full_page'];
+/**
+ * Build the `WHERE` clause for a capture window.
+ *
+ * **Every caller value is a bound parameter and none is interpolated**, on the
+ * same structural argument `ledger.ts` makes: the only strings reaching the SQL
+ * text are column names written in this file, so there is no path that
+ * concatenates a caller's string into a statement and nothing to review for
+ * whether a particular value was escaped.
+ */
+function buildCaptureConditions(window) {
+    const clauses = [];
+    const parameters = [];
+    if (window.since !== undefined) {
+        clauses.push('taken_at >= ?');
+        parameters.push(window.since);
+    }
+    if (window.until !== undefined) {
+        clauses.push('taken_at < ?');
+        parameters.push(window.until);
+    }
+    if (window.claimId !== undefined) {
+        clauses.push('claim_id = ?');
+        parameters.push(window.claimId);
+    }
+    return {
+        sql: clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`,
+        parameters,
+    };
+}
+/** Fold rows into a cost, applying the per-row token formula as it goes. */
+function toCost(rows) {
+    let bytes = 0;
+    let estimatedTokens = 0;
+    let downscaled = 0;
+    let warned = 0;
+    for (const row of rows) {
+        bytes += row.bytes;
+        estimatedTokens += estimateTokens(row.width, row.height);
+        if (row.width !== row.source_width || row.height !== row.source_height) {
+            downscaled += 1;
+        }
+        if (row.warned === 1) {
+            warned += 1;
+        }
+    }
+    return { captures: rows.length, bytes, estimatedTokens, downscaled, warned };
+}
+/** Split rows by their grouping column, preserving the order SQLite returned. */
+function toGroups(rows) {
+    const buckets = new Map();
+    for (const row of rows) {
+        const bucket = buckets.get(row.grouped);
+        if (bucket === undefined) {
+            buckets.set(row.grouped, [row]);
+        }
+        else {
+            bucket.push(row);
+        }
+    }
+    return ([...buckets.entries()]
+        .map(([group, groupRows]) => ({ group, ...toCost(groupRows) }))
+        // Biggest first, because the question a breakdown answers is "what is this
+        // costing me" and the answer is at the top. Ties break by name so the
+        // ordering is total and two runs over the same data render identically.
+        .sort((a, b) => b.estimatedTokens - a.estimatedTokens || a.group.localeCompare(b.group)));
+}
+/**
+ * The most escalation reasons one rollup will return.
+ *
+ * Bounded for the reason `ledger.ts` bounds its slice: both tables grow without
+ * limit and one consumer of this is assembling output a person reads. The
+ * counts above are unbounded because a count of a million rows is still one
+ * number; a *list* of a million reasons is not.
+ */
+export const MAXIMUM_ESCALATION_REASONS = 50;
+/**
+ * What the captures in a window cost.
+ *
+ * Three statements over one table, all sharing the window's predicate and the
+ * `captures_taken_at` index the schema created for "the rollup". Three rather
+ * than one because they answer three shapes of question — a total, two
+ * breakdowns, and a list of written reasons — and a single query returning all
+ * of them would either be a union of incompatible row shapes or a cross join
+ * that multiplies the totals by the number of groups.
+ *
+ * **The totals are not derived from the breakdowns**, though they could be.
+ * Summing `byTier` would give the same number for one query less. It is
+ * computed separately because the two are then independent readings of the
+ * same rows: if a tier ever appears that the breakdown does not know about,
+ * the total still counts it and the two disagree visibly, rather than the row
+ * disappearing from both.
+ */
+export function readCaptureRollup(db, window = {}) {
+    const conditions = buildCaptureConditions(window);
+    const totalRows = db
+        .prepare(`SELECT width, height, source_width, source_height, bytes, warned, '' AS grouped
+         FROM captures${conditions.sql}`)
+        .all(...conditions.parameters);
+    const tierRows = db
+        .prepare(`SELECT width, height, source_width, source_height, bytes, warned, tier AS grouped
+         FROM captures${conditions.sql}`)
+        .all(...conditions.parameters);
+    const kindRows = db
+        .prepare(`SELECT width, height, source_width, source_height, bytes, warned, kind AS grouped
+         FROM captures${conditions.sql}`)
+        .all(...conditions.parameters);
+    const reasonWhere = conditions.sql === ''
+        ? ' WHERE reason IS NOT NULL'
+        : `${conditions.sql} AND reason IS NOT NULL`;
+    const reasonRows = db
+        .prepare(`SELECT id, taken_at, reason FROM captures${reasonWhere}
+       ORDER BY taken_at DESC, id DESC LIMIT ?`)
+        .all(...conditions.parameters, MAXIMUM_ESCALATION_REASONS);
+    return {
+        window,
+        total: toCost(totalRows),
+        byTier: toGroups(tierRows),
+        byKind: toGroups(kindRows),
+        escalationReasons: reasonRows.map((row) => ({
+            captureId: row.id,
+            takenAt: row.taken_at,
+            reason: row.reason,
+        })),
+    };
+}
+/** Fold comparison rows into outcomes plus their distinct settings triples. */
+function toOutcomes(rows) {
+    let changed = 0;
+    let truncated = 0;
+    // Insertion-ordered, and the query returns most recent first, so the
+    // settings come out in the order they were last used.
+    const settings = new Map();
+    for (const row of rows) {
+        if (row.changed === 1) {
+            changed += 1;
+        }
+        if (row.truncated === 1) {
+            truncated += 1;
+        }
+        const key = `${String(row.colour_tolerance)}|${String(row.minimum_region_area)}|${String(row.maximum_regions)}`;
+        const existing = settings.get(key);
+        if (existing === undefined) {
+            settings.set(key, { row, comparisons: 1, changed: row.changed === 1 ? 1 : 0 });
+        }
+        else {
+            existing.comparisons += 1;
+            existing.changed += row.changed === 1 ? 1 : 0;
+        }
+    }
+    return {
+        comparisons: rows.length,
+        changed,
+        truncated,
+        settings: [...settings.values()].map((entry) => ({
+            colourTolerance: entry.row.colour_tolerance,
+            minimumRegionArea: entry.row.minimum_region_area,
+            maximumRegions: entry.row.maximum_regions,
+            comparisons: entry.comparisons,
+            changed: entry.changed,
+        })),
+    };
+}
+const DIFF_COLUMNS = 'colour_tolerance, minimum_region_area, maximum_regions, changed, truncated, at';
+/**
+ * What diffs did around one capture, in both directions.
+ *
+ * **Two single-key lookups, one per index.** `comparisons_source` is
+ * `(source_capture_id, at DESC)`, so the source side gets its ordering from
+ * the index rather than from a sort; `comparisons_target` is the target key
+ * alone, so that side is a key lookup and an ordering the query asks for.
+ * Reading both directions in one statement would mean an `OR` across two
+ * different indexes, which is the shape that turns two lookups into a scan.
+ *
+ * `limit` bounds the rows each direction folds, defaulted and clamped by
+ * `ledger.ts`'s {@link clampLimit} — reused rather than restated, so the page
+ * sizes of the two readers in this directory cannot drift apart.
+ */
+export function readCaptureDiffActivity(db, captureId, limit) {
+    const bound = clampLimit(limit);
+    const sourceRows = db
+        .prepare(`SELECT ${DIFF_COLUMNS} FROM comparisons WHERE source_capture_id = ?
+       ORDER BY at DESC, id DESC LIMIT ?`)
+        .all(captureId, bound);
+    const targetRows = db
+        .prepare(`SELECT ${DIFF_COLUMNS} FROM comparisons WHERE target_capture_id = ?
+       ORDER BY at DESC, id DESC LIMIT ?`)
+        .all(captureId, bound);
+    return {
+        captureId,
+        asSource: toOutcomes(sourceRows),
+        asTarget: toOutcomes(targetRows),
+    };
+}
+export function readMostDiffedTargets(db, limit) {
+    const bound = clampLimit(limit);
+    const rows = db
+        .prepare(`SELECT c.target_capture_id AS capture_id,
+              COUNT(*) AS comparisons,
+              SUM(c.changed) AS changed,
+              p.url AS url,
+              p.taken_at AS taken_at
+         FROM comparisons c
+         -- A left join, not an inner one: a comparison naming a capture whose
+         -- row is gone is still a comparison that happened, and dropping it
+         -- would quietly shrink a count whose whole purpose is to be compared
+         -- against another count.
+         LEFT JOIN captures p ON p.id = c.target_capture_id
+        GROUP BY c.target_capture_id
+        ORDER BY comparisons DESC, c.target_capture_id ASC
+        LIMIT ?`)
+        .all(bound);
+    return rows.map((row) => ({
+        captureId: row.capture_id,
+        comparisons: row.comparisons,
+        changed: row.changed,
+        url: row.url,
+        takenAt: row.taken_at,
+    }));
+}