d41d118 · 7e54c3a · bda4b90
@@ -11,3 +11,14 @@
A finding must carry a probe: `{ kind: "query" | "measurement", what, number, at
The terminal door is the palette entry "Maintenance duty runs" (`src/tui/screens/maintainruns.ts`): the same rows through the same read, offered only to a forge admin; anyone else is offered nothing and sees no rows.
Each run is bounded: a duty that has not answered in 30 seconds reads `failed: timed out` and the next duty runs (the late duty keeps its slot until it settles, so it never overlaps itself). A duty name must be lowercase words and dashes and unique, or the runner refuses to start. Each duty keeps its newest 200 rows; older ones are deleted after each run. A finding that says nothing reads `refused: a finding says nothing`. A non-admin's token reads 403 `forbidden`.
## efficiency-watcher (#7558)
Hourly, the duty records what each cost read (`efficiency_sample`, one row per cause per hour) and judges it (`src/efficiency/`):
- **Causes** (`causes.ts`): npm registry bytes received, bytes from every other destination (image pulls, git fetch and clone, apps), the machine's CPU-seconds, and the install cache hit rate. Each has a floor and, for the byte causes, an absolute ceiling. The hit rate is the share of the hour's contained installs (`meteredInstall`, counted in `installs.ts`, in memory) that fetched under 1 MiB from the registry (`NPM_MISS_BYTES`); under 5 installs in the hour there is no reading. It is a *falling* cause: its floor is on the baseline (a baseline under 50% is not fallen from). Not measured by cause: per-run bytes and peak memory, which have no counter to read yet.
- **Baseline** (`baseline.ts`): the median of the same hour of the day over the last 7 days; under 3 days of history there is none, so a new forge files nothing by doubling.
- **Files when** (`judge.ts`) an hour is at least 2x its baseline for 2 hours running (a hit rate: at most half its baseline for 2 hours running), or at or over the ceiling. The reading is the rolling last hour of the egress tally, taken when the duty runs.
- **One issue per cause** on the forge's repository (`FORGE_REPO`, as its owner): the cause, the number, the baseline and the code path. A comment each hour it still stands; closed with a note once the cost has been back under for 24 hours. If a person closes it, the next finding opens a new one.
- The series is the `efficiency` board source (admin boards), so a board can chart it.
- **Where an admin sees it.** The run is a row on the admin's "Maintenance duty runs" screen (terminal palette; `GET /api/v1/maintenance/runs`) under `efficiency-watcher`, with each finding's probe. The hourly series is the `efficiency` source on /boards (filter `cause`, value `value`; the hit rate is 0..1). If `FORGE_REPO` is unset or names no repository, findings still show on the run and its actions say `filed nothing: <why>`.
@@ -34,6 +34,7 @@
export const GUIDE: Readonly<Record<string, Guide>> = {
  tokens: { name: "API tokens", rows: "tokens", kind: "events" },
  adminActions: { name: "Admin actions", rows: "admin actions", kind: "events" },
  machine: { name: "Machine readings", rows: "15-second readings", kind: "samples", value: "cpu_cores", filter: { column: "target", op: "eq", value: "forge" } },
  efficiency: { name: "Efficiency by cause", rows: "hourly readings", kind: "samples", value: "value", filter: { column: "cause", op: "eq", value: "npm-registry-bytes" } },
  reach: { name: "Visitors and page speed", rows: "daily figures", kind: "samples", value: "value", filter: { column: "metric", op: "eq", value: "visitors" } },
  app_vital: { name: "App page speed", rows: "app-days", kind: "samples", value: "load_p75" },
  keeperReleases: { name: "Releases", rows: "releases", kind: "events" },
@@ -191,6 +191,17 @@
export const SOURCES: Readonly<Record<string, Source>> = {
    time: "created_at",
    columns: { id: "text", kind: "text", repo_id: "text", actor_id: "text", created_at: "time" },
  },
  // The efficiency watcher's hourly readings by cause (`efficiency/`, #7558).
  efficiency: {
    table: "efficiency_sample",
    owner: "admin",
    time: "hour",
    columns: { cause: "text", hour: "time", value: "number" },
    docs: {
      cause: "npm-registry-bytes, egress-other-bytes, cpu-seconds or install-cache-hit-rate (0..1)",
      value: "bytes received (or CPU-seconds, or share of installs that hit the cache) in the hour up to the reading",
    },
  },
  // What the machine used (`boards/sampler.ts`, kept by `boards/ring.ts`):
  // 15-s points for the last day, 5-min points before that, never both
  // for one moment.
@@ -18,9 +18,10 @@
import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { meterEgress } from "../apps/egress.ts";
import { dirname, join } from "node:path";
import { meterEgress } from "../apps/egress.ts";
import { formatBytes } from "../core/storage.ts";
import { noteInstall } from "../efficiency/installs.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { fillable } from "./fillable.ts";
import { lend } from "./install_evict.ts";
@@ -85,6 +86,7 @@
export async function meteredInstall<T>(
    if (options.fetched === true) write(installFetchedLine(fetched));
    const missed = npmMissLine(meter.npm());
    if (missed !== undefined) write(missed);
    noteInstall(missed !== undefined); // the hit-rate counter the efficiency watcher reads (#7558)
  }
}
@@ -0,0 +1,1 @@
23d0042136af8ee70c73f30c9b29cd3ce1e9adf1d8721b850f56d686bfaed437
@@ -0,0 +1,16 @@
// The efficiency watcher (#7558): one reading per cause per hour, and the one
// finding standing per cause. Additive. Both tables are small (a few causes,
// 24 rows a day each, pruned past 9 days) and read by primary key only.
export default `
  CREATE TABLE efficiency_sample (
    cause TEXT NOT NULL,
    hour TEXT NOT NULL,
    value REAL NOT NULL,
    PRIMARY KEY (cause, hour)
  ) WITHOUT ROWID;
  CREATE TABLE efficiency_finding (
    cause TEXT PRIMARY KEY,
    issue_id TEXT NOT NULL,
    last_bad TEXT NOT NULL
  ) WITHOUT ROWID;
  `;
@@ -0,0 +1,28 @@
/** The baseline (#7558): the median of the same hour of the day over the last seven days. Plain data in, a number out. */
export const HOUR_MS = 3_600_000;
export const BASELINE_DAYS = 7;
/** Fewer days of history than this and there is no baseline: a new forge files nothing by doubling. */
export const MIN_DAYS = 3;
/** hour start (ms) → value, for one cause. */
export type Series = ReadonlyMap<number, number>;
export const hourStart = (ms: number): number => Math.floor(ms / HOUR_MS) * HOUR_MS;
export function median(values: readonly number[]): number | undefined {
  if (values.length === 0) return undefined;
  const s = [...values].sort((a, b) => a - b);
  const m = s.length >> 1;
  return s.length % 2 === 1 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
}
/** Median of the readings at `hour` minus 1..7 days; undefined with fewer than MIN_DAYS of them. */
export function baselineAt(series: Series, hour: number): number | undefined {
  const same: number[] = [];
  for (let d = 1; d <= BASELINE_DAYS; d++) {
    const v = series.get(hour - d * 24 * HOUR_MS);
    if (v !== undefined) same.push(v);
  }
  return same.length < MIN_DAYS ? undefined : median(same);
}
@@ -0,0 +1,74 @@
/** What the efficiency watcher measures (#7558): each cost by cause, its unit, its floor and ceiling, and the code path that starts it. Plain data. */
export interface Cause {
  /** Lowercase words and dashes; the sample's `cause`. */
  readonly id: string;
  readonly label: string;
  /** "bytes", "seconds" or "ratio" (0 to 1): the unit every number of this cause is in, hourly. */
  readonly unit: "bytes" | "seconds" | "ratio";
      
        sentinelcrew
        4d ago
        
      
      Comment says bytes or seconds; the type also has "ratio". Update.
    
  /** "rising" is bad when it doubles; "falling" (a hit rate) is bad when it halves. */
  readonly direction: "rising" | "falling";
  /**
   * Rising: an hour below this is never "doubled" (a baseline of nothing makes any byte a doubling).
   * Falling: a baseline below this is never "fallen from" (a cache that rarely hit has nothing to lose).
   */
  readonly floor: number;
  /** An hour at or above this files at once, baseline or not. */
  readonly ceiling: number | undefined;
  /** Where the cost starts, named in the finding. */
  readonly path: string;
}
const MiB = 1024 ** 2;
const GiB = 1024 ** 3;
export const CAUSES: readonly Cause[] = [
  {
    id: "npm-registry-bytes",
    label: "npm registry bytes received",
    unit: "bytes",
    direction: "rising",
    floor: 256 * MiB,
    ceiling: 4 * GiB,
    path: "an install step (`bun install` in `src/checks/service.ts`, an app's install in `src/apps/`) reaching registry.npmjs.org:443 through the egress proxy (`src/apps/egress.ts`, `NPM_REGISTRY`); a cold or unshared bun cache starts it",
  },
  {
    id: "egress-other-bytes",
    label: "bytes received from every other destination (image pulls, git fetch and clone, apps)",
    unit: "bytes",
    direction: "rising",
    floor: 512 * MiB,
    ceiling: 10 * GiB,
    path: "a cell or app reaching a host other than the registry through the egress proxy (`src/apps/egress.ts`, `egressTotals`); the destination is in the forge's /metrics `forge_egress_received_bytes_total`",
  },
  {
    id: "cpu-seconds",
    label: "CPU-seconds used by the forge's machine",
    unit: "seconds",
    direction: "rising",
    floor: 900,
    ceiling: undefined,
    path: "whatever ran hot: the 15 s sampler (`src/boards/sampler.ts`) names cpu per cell label in the `machine` source",
  },
  {
    id: "install-cache-hit-rate",
    label: "install cache hit rate (installs that fetched under 1 MiB from the npm registry)",
    unit: "ratio",
    direction: "falling",
    floor: 0.5,
    ceiling: undefined,
    path: "a contained install (`meteredInstall` in `src/checks/install.ts`) fetching over 1 MiB from the registry because the shared cache (`prefillInstallCache`, `checkInstallCache`) was cold, evicted (`src/checks/install_evict.ts`) or not filled; counted in `src/efficiency/installs.ts`",
  },
];
export const causeOf = (id: string): Cause | undefined => CAUSES.find((c) => c.id === id);
export function show(c: Cause, n: number): string {
  if (c.unit === "ratio") return `${(n * 100).toFixed(1)}%`;
  if (c.unit === "seconds") return `${Math.round(n)} CPU-seconds`;
  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
  let v = n;
  let i = 0;
  while (v >= 1024 && i < units.length - 1) (v /= 1024), i++;
  return `${i === 0 ? v : v.toFixed(2)} ${units[i]}`;
}
@@ -0,0 +1,32 @@
/** The words of a finding and its comments (#7558): the cause, the number, the baseline, the code path. */
import { show, type Cause } from "./causes.ts";
import type { HourVerdict, Why } from "./judge.ts";
const at = (ms: number): string => `${new Date(ms).toISOString().slice(0, 13)}:00 UTC`;
export const titleOf = (c: Cause): string => `Efficiency: ${c.label} is far ${c.direction === "falling" ? "below" : "above"} its usual`;
export function numbers(c: Cause, v: HourVerdict, why: Why): string {
  const base = v.baseline === undefined ? "no baseline yet" : `baseline ${show(c, v.baseline)} (median of this hour over the last 7 days)`;
  const rule =
    why === "ceiling"
      ? `at or over the ceiling of ${show(c, c.ceiling ?? 0)}`
      : why === "fell"
        ? "at most half its baseline for 2 hours running"
        : "at least 2x its baseline for 2 hours running";
  return `${show(c, v.value)} in the hour of ${at(v.hour)}; ${base}; ${rule}.`;
}
export function bodyOf(c: Cause, v: HourVerdict, why: Why): string {
  return (
    `The efficiency watcher (duty \`efficiency-watcher\`) found **${c.label}**: ${numbers(c, v, why)}\n\n` +
    `Code path that starts the cost: ${c.path}.\n\n` +
    `This issue stands while the cost does: it gets a comment each hour it is still bad, and is closed with a note once it has been back under for 24 hours. ` +
    `The hourly series is the \`efficiency\` board source.`
  );
}
export const commentOf = (c: Cause, v: HourVerdict, why: Why): string => `Still bad: ${numbers(c, v, why)}`;
export const closingNote = (c: Cause): string => `${c.label} has been back under its baseline and ceiling for 24 hours. Closing; a new finding opens if it returns.`;
@@ -0,0 +1,37 @@
/** The install cache counter (#7558): each contained install, and whether it missed the shared cache. In memory, the last hour only. */
import { HOUR_MS } from "./baseline.ts";
/** Fewer installs than this in the hour and there is no hit rate: one install is not a rate. */
export const MIN_INSTALLS = 5;
const seen: { at: number; missed: boolean }[] = [];
/** One contained install finished; `missed` when the registry sent more than `NPM_MISS_BYTES` (`checks/install.ts`). */
export function noteInstall(missed: boolean, now: number = Date.now()): void {
  seen.push({ at: now, missed });
  prune(now);
}
function prune(now: number): void {
  let n = 0;
  while (n < seen.length && seen[n]!.at <= now - HOUR_MS) n++;
  if (n > 0) seen.splice(0, n);
}
/** Installs in the hour up to `now` and how many missed. */
export function installsLastHour(now: number): { installs: number; misses: number } {
  prune(now);
  return { installs: seen.length, misses: seen.filter((s) => s.missed).length };
}
/** Share of the last hour's installs that hit the cache, 0..1; undefined under MIN_INSTALLS. */
export function hitRateLastHour(now: number): number | undefined {
  const { installs, misses } = installsLastHour(now);
  return installs < MIN_INSTALLS ? undefined : (installs - misses) / installs;
}
/** For tests: forget every install. */
export function resetInstalls(): void {
  seen.length = 0;
}
@@ -0,0 +1,45 @@
/** When a cost is bad (#7558): 2x its baseline for 2 hours running, a hit rate at or under half its baseline for 2 hours running, or at or over its ceiling. */
import { baselineAt, HOUR_MS, type Series } from "./baseline.ts";
import type { Cause } from "./causes.ts";
export const DOUBLE = 2;
export type Why = "ceiling" | "doubled" | "fell";
export const FALL = 0.5;
export const HOURS_TO_FILE = 2;
export interface HourVerdict {
  readonly hour: number;
  readonly value: number;
  readonly baseline: number | undefined;
  readonly doubled: boolean;
  /** A falling cause (a hit rate) at or under FALL of its baseline, the baseline itself at or over the cause's floor. */
  readonly fell: boolean;
  readonly overCeiling: boolean;
}
export function hourVerdict(c: Cause, series: Series, hour: number): HourVerdict | undefined {
  const value = series.get(hour);
  if (value === undefined) return undefined;
  const baseline = baselineAt(series, hour);
  const doubled = c.direction === "rising" && baseline !== undefined && value >= c.floor && value >= DOUBLE * baseline;
  const fell = c.direction === "falling" && baseline !== undefined && baseline >= c.floor && value <= FALL * baseline;
  const overCeiling = c.ceiling !== undefined && value >= c.ceiling;
  return { hour, value, baseline, doubled, fell, overCeiling };
}
export const isBad = (v: HourVerdict | undefined): boolean => v !== undefined && (v.doubled || v.fell || v.overCeiling);
/** The verdict that makes the cost stand at `hour`: the ceiling at once, or the doubling this hour and the one before (a falling cause: the fall). */
export function standing(c: Cause, series: Series, hour: number): { now: HourVerdict; why: Why } | undefined {
  const now = hourVerdict(c, series, hour);
  if (now === undefined) return undefined;
  if (now.overCeiling) return { now, why: "ceiling" };
  let run = 0;
  for (let i = 0; i < HOURS_TO_FILE; i++) {
    const v = hourVerdict(c, series, hour - i * HOUR_MS);
    if (v?.doubled || v?.fell) run++;
  }
  return run === HOURS_TO_FILE ? { now, why: c.direction === "falling" ? "fell" : "doubled" } : undefined;
}
@@ -0,0 +1,28 @@
/** What each cause reads right now, from the figures the forge already keeps (#7546's egress tally, the 15 s machine sampler). */
import type { Database } from "bun:sqlite";
import { hitRateLastHour } from "./installs.ts";
import { egressTotals, NPM_REGISTRY } from "../apps/egress.ts";
export type Readings = Readonly<Record<string, number>>;
/** CPU-seconds the machine used over the hour up to `now`: mean cores of the 15 s points times 3600. */
export function cpuSecondsLastHour(db: Database, now: number): number | undefined {
  const r = db
    .query("SELECT AVG(cpu_cores) AS cores FROM machine_sample WHERE target = 'node' AND step = 15 AND cpu_cores IS NOT NULL AND at > ?1")
    .get(new Date(now - 3_600_000).toISOString()) as { cores: number | null } | null;
  return r?.cores == null ? undefined : r.cores * 3600;
}
export function readNow(db: Database, now: number): Readings {
  const totals = egressTotals(now);
  const out: Record<string, number> = {
    "npm-registry-bytes": totals.find((t) => t.destination === NPM_REGISTRY)?.bytesInLastHour ?? 0,
    "egress-other-bytes": totals.filter((t) => t.destination !== NPM_REGISTRY).reduce((n, t) => n + t.bytesInLastHour, 0),
  };
  const cpu = cpuSecondsLastHour(db, now);
  if (cpu !== undefined) out["cpu-seconds"] = cpu;
  const hit = hitRateLastHour(now);
  if (hit !== undefined) out["install-cache-hit-rate"] = hit;
  return out;
}
@@ -0,0 +1,54 @@
/** `efficiency_sample` and `efficiency_finding`: the hourly readings and the finding standing per cause. */
import type { Database } from "bun:sqlite";
import { BASELINE_DAYS, HOUR_MS, type Series } from "./baseline.ts";
import { causeOf } from "./causes.ts";
const iso = (ms: number): string => new Date(ms).toISOString();
/**
 * One reading for the hour starting at `hour`. Two readings in one hour (a restart, a manual tick)
      
        sentinelcrew
        4d ago
        outdated
      
      MAX is wrong for a falling cause: a later, higher hit-rate reading in the same hour masks the fall. Choose MIN or MAX by the cause's direction and test it.
    
 * keep the worse: the larger for a rising cost, the smaller for a falling one (a hit rate), so a
 * later, kinder reading never hides a bad one.
 */
export function putSample(db: Database, cause: string, hour: number, value: number): void {
  const worse = causeOf(cause)?.direction === "falling" ? "MIN" : "MAX";
  db.query(
    `INSERT INTO efficiency_sample (cause, hour, value) VALUES (?1, ?2, ?3) ON CONFLICT (cause, hour) DO UPDATE SET value = ${worse}(value, excluded.value)`,
  ).run(cause, iso(hour), value);
}
/** The cause's readings of the last 8 days up to `hour`. */
export function readSeries(db: Database, cause: string, hour: number): Series {
  const rows = db
    .query("SELECT hour, value FROM efficiency_sample WHERE cause = ?1 AND hour > ?2 AND hour <= ?3")
    .all(cause, iso(hour - (BASELINE_DAYS + 1) * 24 * HOUR_MS), iso(hour)) as { hour: string; value: number }[];
  return new Map(rows.map((r) => [Date.parse(r.hour), r.value]));
}
export function pruneSamples(db: Database, now: number): void {
  db.query("DELETE FROM efficiency_sample WHERE hour < ?1").run(iso(now - (BASELINE_DAYS + 2) * 24 * HOUR_MS));
}
export interface Standing {
  readonly cause: string;
  readonly issueId: string;
  readonly lastBad: number;
}
export function standingOf(db: Database, cause: string): Standing | undefined {
  const r = db.query("SELECT cause, issue_id, last_bad FROM efficiency_finding WHERE cause = ?1").get(cause) as
    | { cause: string; issue_id: string; last_bad: string }
    | null;
  return r ? { cause: r.cause, issueId: r.issue_id, lastBad: Date.parse(r.last_bad) } : undefined;
}
export function putStanding(db: Database, s: Standing): void {
  db.query(
    "INSERT INTO efficiency_finding (cause, issue_id, last_bad) VALUES (?1, ?2, ?3) ON CONFLICT (cause) DO UPDATE SET issue_id = excluded.issue_id, last_bad = excluded.last_bad",
  ).run(s.cause, s.issueId, iso(s.lastBad));
}
export function dropStanding(db: Database, cause: string): void {
  db.query("DELETE FROM efficiency_finding WHERE cause = ?1").run(cause);
}
@@ -0,0 +1,89 @@
/**
 * The efficiency watcher's pass (#7558): record this hour's readings, judge each cause against its
 * baseline, and keep one issue per cause — filed when it stands, commented while it does, closed
 * with a note once it has been back under for 24 hours.
 */
import type { App } from "../app.ts";
import { addComment, openIssue, setIssueState } from "../actions/issues.ts";
import { getIssueById } from "../core/issues.ts";
import { getRepo } from "../core/repos.ts";
import { getUserById } from "../core/users.ts";
import type { DutyResult, Finding } from "../maintain/duty.ts";
import { HOUR_MS, hourStart } from "./baseline.ts";
import { CAUSES } from "./causes.ts";
import { bodyOf, closingNote, commentOf, numbers, titleOf } from "./finding.ts";
import { isBad, standing, hourVerdict } from "./judge.ts";
import { readNow, type Readings } from "./readings.ts";
import { dropStanding, pruneSamples, putSample, putStanding, readSeries, standingOf } from "./store.ts";
export const CLEAR_AFTER_MS = 24 * HOUR_MS;
export function watch(app: App, now: number, readings: Readings = readNow(app.db, now)): DutyResult {
  const { db } = app;
  const hour = hourStart(now);
  const findings: Finding[] = [];
  const actions: string[] = [];
  const [owner = "", name = ""] = (app.config.forgeRepo ?? "").split("/");
  const repo = owner && name ? getRepo(db, owner, name) : undefined;
  const actor = repo ? getUserById(db, repo.ownerId) : undefined;
  for (const c of CAUSES) {
    const reading = readings[c.id];
    if (reading !== undefined) putSample(db, c.id, hour, reading);
    const series = readSeries(db, c.id, hour);
    const stands = standing(c, series, hour);
    const kept = standingOf(db, c.id);
    const issue = kept ? getIssueById(db, kept.issueId) : undefined;
    const open = issue !== undefined && issue.state === "open";
    if (stands !== undefined) {
      findings.push({
        summary: `${c.label}: ${numbers(c, stands.now, stands.why)}`,
        probe: { kind: "measurement", what: `${c.label} (${c.unit}) in the hour from ${new Date(hour).toISOString()}`, number: stands.now.value, at: new Date(now).toISOString() },
      });
      if (repo === undefined || actor === undefined) continue;
      if (open && kept !== undefined) {
        // One comment per hour: a second pass in the same hour adds nothing.
        if (kept.lastBad < hour) {
          addComment(app, actor, repo, issue, commentOf(c, stands.now, stands.why));
          putStanding(db, { ...kept, lastBad: hour });
          actions.push(`commented on #${issue.number} (${c.id})`);
        }
        continue;
      }
      const filed = openIssue(app, actor, repo, { title: titleOf(c), body: bodyOf(c, stands.now, stands.why) });
      if (filed.ok) {
        putStanding(db, { cause: c.id, issueId: filed.value.id, lastBad: hour });
        actions.push(`filed #${filed.value.number} (${c.id})`);
      }
      continue;
    }
    if (kept === undefined) continue;
    if (!open) {
      dropStanding(db, c.id); // someone closed it: the next standing cost files anew
      continue;
    }
    const lastBad = isBad(hourVerdict(c, series, hour)) ? hour : kept.lastBad;
    if (lastBad !== kept.lastBad) putStanding(db, { ...kept, lastBad });
    if (repo !== undefined && actor !== undefined && now - lastBad >= CLEAR_AFTER_MS) {
      addComment(app, actor, repo, issue, closingNote(c));
      setIssueState(app, actor, repo, issue, "closed");
      dropStanding(db, c.id);
      actions.push(`closed #${issue.number} (${c.id}) after 24 hours clear`);
    }
  }
  pruneSamples(db, now);
  if (findings.length > 0 && (repo === undefined || actor === undefined)) {
    const why = !app.config.forgeRepo
      ? "FORGE_REPO is not set"
      : !owner || !name
        ? `FORGE_REPO "${app.config.forgeRepo}" is not owner/name`
        : repo === undefined
          ? `FORGE_REPO "${app.config.forgeRepo}" names no repository on this forge`
          : "the repository's owner is not a user";
    actions.push(`filed nothing: ${why}, so there is no repository to file ${findings.length} finding(s) in`);
  }
  return { findings, actions };
}
@@ -0,0 +1,12 @@
/** The efficiency watcher (#7558): hourly cost by cause against a 7-day baseline; see `src/efficiency/`. */
import type { Duty } from "../duty.ts";
import { watch } from "../../efficiency/watch.ts";
export const duty: Duty = {
  name: "efficiency-watcher",
  intervalMs: 3_600_000,
  run({ app, now }) {
    return app === undefined ? { findings: [], actions: [] } : watch(app, now.getTime());
  },
};
@@ -1,6 +1,7 @@
/** What a maintenance duty is (#11204): a name, an interval and a handler; plain data in, plain data out. */
import type { Database } from "bun:sqlite";
import type { App } from "../app.ts";
/** The number a finding rests on and when it was read: a query's result or a measurement. */
export interface Probe {
@@ -26,6 +27,8 @@
export interface DutyResult {
export interface DutyContext {
  readonly db: Database;
  readonly now: Date;
  /** The running app, for a duty that files or comments through the same actions a person uses. */
  readonly app?: App | undefined;
}
export interface Duty {
@@ -2,5 +2,6 @@
import type { Duty } from "./duty.ts";
import { duty as pullsWaiting } from "./duties/stale_pulls.ts";
import { duty as efficiencyWatcher } from "./duties/efficiency_watcher.ts";
export const duties: readonly Duty[] = [pullsWaiting];
export const duties: readonly Duty[] = [pullsWaiting, efficiencyWatcher];
@@ -43,7 +43,7 @@
export function startMaintain(app: App, options: { duties?: readonly Duty[]; eve
    let outcome = "ok";
    try {
      // The duty keeps its `running` slot until it really settles, so a timed-out duty never overlaps itself.
      const work = Promise.resolve().then(() => duty.run({ db: app.db, now }));
      const work = Promise.resolve().then(() => duty.run({ db: app.db, now, app }));
      work.then(() => running.delete(duty.name), () => running.delete(duty.name));
      let timer: ReturnType<typeof setTimeout> | undefined;
      const deadline = new Promise<never>((_, reject) => {
@@ -0,0 +1,32 @@
/** The baseline (#7558): the median of the same hour over the last seven days, by hand. */
import { expect, test } from "bun:test";
import { baselineAt, median, MIN_DAYS } from "../src/efficiency/baseline.ts";
import { DAY, T0 } from "./helpers/efficiency.ts";
test("the median of an odd and an even count, by hand", () => {
  expect(median([5, 1, 3])).toBe(3);
  expect(median([4, 1, 3, 100])).toBe(3.5);
  expect(median([])).toBeUndefined();
});
test("the baseline is the median of this hour of the day over the last 7 days, and nothing else", () => {
  const s = new Map<number, number>();
  [10, 20, 30, 40, 50, 60, 70].forEach((v, i) => s.set(T0 - (i + 1) * DAY, v)); // same hour, 1..7 days ago
  s.set(T0 - 3_600_000, 9999); // another hour: not the same hour of the day
  s.set(T0 - 8 * DAY, 9999); // eight days ago: outside the window
  expect(baselineAt(s, T0)).toBe(40);
});
test("a spike is a median's outlier: one bad day does not move the baseline", () => {
  const s = new Map<number, number>();
  [10, 10, 10, 10, 10, 10, 1000].forEach((v, i) => s.set(T0 - (i + 1) * DAY, v));
  expect(baselineAt(s, T0)).toBe(10);
});
test("under three days of history there is no baseline", () => {
  const s = new Map<number, number>();
  for (let d = 1; d < MIN_DAYS; d++) s.set(T0 - d * DAY, 10);
  expect(baselineAt(s, T0)).toBeUndefined();
  s.set(T0 - MIN_DAYS * DAY, 10);
  expect(baselineAt(s, T0)).toBe(10);
});
@@ -0,0 +1,45 @@
/** Closing (#7558): back under for 24 hours closes the issue with a note; sooner does not. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { HOUR_MS } from "../src/efficiency/baseline.ts";
import { quietLogs } from "./helpers/globals.ts";
import { commentsOf, forge, flat, issuesOf, MiB, NPM, T0, watch } from "./helpers/efficiency.ts";
quietLogs();
let f: Awaited<ReturnType<typeof forge>>;
beforeAll(async () => { f = await forge(); });
afterAll(() => f.done());
test("closed with a note after 24 hours back under, not before; a relapse resets the clock", () => {
  flat(f.app, T0);
  const bad = { [NPM]: 600 * MiB };
  const ok = { [NPM]: 50 * MiB };
  watch(f.app, T0 + 600_000, bad);
  watch(f.app, T0 + HOUR_MS + 600_000, bad); // files; last bad hour is T0+1h
  const [issue] = issuesOf(f.app, f.repoId);
  expect(issue!.state).toBe("open");
  watch(f.app, T0 + 2 * HOUR_MS + 600_000, ok);
  watch(f.app, T0 + 20 * HOUR_MS + 600_000, ok);
  expect(issuesOf(f.app, f.repoId)[0]!.state).toBe("open");
  watch(f.app, T0 + 25 * HOUR_MS + 300_000, ok); // 24 h after the last bad hour
  const after = issuesOf(f.app, f.repoId)[0]!;
  expect(after.state).toBe("closed");
  expect(commentsOf(f.app, issue!.id).at(-1)).toContain("back under");
  expect(commentsOf(f.app, issue!.id).at(-1)).toContain("24 hours");
});
test("a single bad hour inside the 24 resets the wait: closing comes 24 hours after it, not before", () => {
  f.app.db.exec("DELETE FROM efficiency_sample; DELETE FROM efficiency_finding; DELETE FROM comment; DELETE FROM issue");
  const base = T0 + 40 * HOUR_MS;
  flat(f.app, base);
  const bad = { [NPM]: 600 * MiB };
  const ok = { [NPM]: 50 * MiB };
  watch(f.app, base + 600_000, bad);
  watch(f.app, base + HOUR_MS + 600_000, bad); // files; last bad hour is base+1h
  watch(f.app, base + 10 * HOUR_MS + 600_000, bad); // a stray bad hour, alone: last bad hour is base+10h
  watch(f.app, base + 26 * HOUR_MS + 600_000, ok); // 25 h after base+1h: would close had the stray done nothing
  expect(issuesOf(f.app, f.repoId)[0]!.state).toBe("open");
  watch(f.app, base + 33 * HOUR_MS + 600_000, ok); // 23 h 10 min after the stray hour
  expect(issuesOf(f.app, f.repoId)[0]!.state).toBe("open");
  watch(f.app, base + 34 * HOUR_MS + 300_000, ok); // 24 h 5 min after the stray hour
  expect(issuesOf(f.app, f.repoId)[0]!.state).toBe("closed");
});
@@ -0,0 +1,43 @@
/** One issue per cause (#7558): a comment while it stands, never a second issue. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { HOUR_MS } from "../src/efficiency/baseline.ts";
import { quietLogs } from "./helpers/globals.ts";
import { commentsOf, forge, flat, issuesOf, MiB, NPM, seed, T0, watch } from "./helpers/efficiency.ts";
quietLogs();
let f: Awaited<ReturnType<typeof forge>>;
beforeAll(async () => { f = await forge(); });
afterAll(() => f.done());
test("a cost that stays bad gets one issue and one comment per hour", () => {
  flat(f.app, T0);
  const bad = { [NPM]: 600 * MiB };
  watch(f.app, T0 + 600_000, bad);
  watch(f.app, T0 + HOUR_MS + 600_000, bad); // files
  watch(f.app, T0 + HOUR_MS + 1_200_000, bad); // same hour again: nothing more
  watch(f.app, T0 + 2 * HOUR_MS + 600_000, bad);
  watch(f.app, T0 + 3 * HOUR_MS + 600_000, bad);
  const issues = issuesOf(f.app, f.repoId);
  expect(issues).toHaveLength(1);
  const notes = commentsOf(f.app, issues[0]!.id);
  expect(notes).toHaveLength(2);
  expect(notes[0]).toContain("Still bad");
  expect(notes[0]).toContain("600.00 MiB");
});
test("another cause files its own issue; a person's close makes the next finding a new issue", () => {
  f.app.db.exec("DELETE FROM efficiency_sample; DELETE FROM efficiency_finding; DELETE FROM comment; DELETE FROM issue");
  const OTHER = "egress-other-bytes";
  flat(f.app, T0);
  seed(f.app, OTHER, T0, 8 * 24, () => 100 * MiB);
  const second = { [NPM]: 600 * MiB, [OTHER]: 5 * 1024 * MiB };
  for (let h = 0; h <= 1; h++) watch(f.app, T0 + h * HOUR_MS + 600_000, second);
  const issues = issuesOf(f.app, f.repoId);
  expect(issues).toHaveLength(2);
  expect(issues.filter((i) => i.title.includes("npm registry bytes"))).toHaveLength(1);
  expect(issues.filter((i) => i.title.includes("every other destination"))).toHaveLength(1);
  f.app.db.exec("UPDATE issue SET state = 'closed' WHERE title LIKE '%npm registry bytes%'");
  watch(f.app, T0 + 2 * HOUR_MS + 600_000, second);
  expect(issuesOf(f.app, f.repoId).filter((i) => i.title.includes("npm registry bytes"))).toHaveLength(2);
  expect(issuesOf(f.app, f.repoId).filter((i) => i.title.includes("every other destination") && i.state === "open")).toHaveLength(1);
});
@@ -0,0 +1,76 @@
/** When a cost is bad (#7558): 2x for 2 hours, or a ceiling; flat files nothing; the #7541 series files within 3 hours. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { HOUR_MS } from "../src/efficiency/baseline.ts";
import { causeOf } from "../src/efficiency/causes.ts";
import { putSample } from "../src/efficiency/store.ts";
import { quietLogs } from "./helpers/globals.ts";
import { forge, flat, issuesOf, MiB, NPM, T0, watch } from "./helpers/efficiency.ts";
quietLogs();
let f: Awaited<ReturnType<typeof forge>>;
beforeAll(async () => { f = await forge(); });
afterAll(() => f.done());
const reset = () => { f.app.db.exec("DELETE FROM efficiency_sample; DELETE FROM efficiency_finding; DELETE FROM comment; DELETE FROM issue"); };
test("a flat series files nothing", () => {
  reset();
  flat(f.app, T0);
  for (let h = 0; h < 6; h++) {
    const r = watch(f.app, T0 + h * HOUR_MS + 600_000, { [NPM]: 50 * MiB });
    expect(r.findings).toEqual([]);
  }
  expect(issuesOf(f.app, f.repoId)).toEqual([]);
});
test("npm bytes jump 10x for 2 hours: one issue with cause, numbers and baseline", () => {
  reset();
  flat(f.app, T0);
  expect(watch(f.app, T0 + 600_000, { [NPM]: 500 * MiB }).findings).toEqual([]); // one hour is not yet two
  expect(issuesOf(f.app, f.repoId)).toEqual([]);
  const r = watch(f.app, T0 + HOUR_MS + 600_000, { [NPM]: 500 * MiB });
  expect(r.findings).toHaveLength(1);
  expect(r.findings[0]!.probe?.number).toBe(500 * MiB);
  const issues = issuesOf(f.app, f.repoId);
  expect(issues).toHaveLength(1);
  expect(issues[0]!.title).toContain("npm registry bytes");
  expect(issues[0]!.body).toContain("500.00 MiB");
  expect(issues[0]!.body).toContain("baseline 50.00 MiB");
  expect(issues[0]!.body).toContain("registry.npmjs.org:443");
  expect(issues[0]!.body).toContain("2x");
});
test("an hour over the ceiling files at once", () => {
  reset();
  flat(f.app, T0);
  watch(f.app, T0 + 600_000, { [NPM]: causeOf(NPM)!.ceiling! });
  expect(issuesOf(f.app, f.repoId)[0]!.body).toContain("ceiling");
});
test("a doubling under the floor is noise and files nothing", () => {
  reset();
  flat(f.app, T0, 1 * MiB);
  watch(f.app, T0 + 600_000, { [NPM]: 10 * MiB });
  watch(f.app, T0 + HOUR_MS + 600_000, { [NPM]: 10 * MiB });
  expect(issuesOf(f.app, f.repoId)).toEqual([]);
});
test("replaying #7541 (~1.25 GiB an hour over a quiet week) files within 3 hours of the first bad hour", () => {
  reset();
  flat(f.app, T0, 40 * MiB);
  const bad = 1.25 * 1024 * MiB;
  let filedAfter = -1;
  for (let h = 0; h < 6 && filedAfter < 0; h++) {
    watch(f.app, T0 + h * HOUR_MS + 3_500_000, { [NPM]: bad });
    if (issuesOf(f.app, f.repoId).length > 0) filedAfter = h + 1;
  }
  expect(filedAfter).toBeGreaterThan(0);
  expect(filedAfter).toBeLessThanOrEqual(3);
});
test("a forge with under three days of history files nothing by doubling", () => {
  reset();
  for (let h = 1; h <= 30; h++) putSample(f.app.db, NPM, T0 - h * HOUR_MS, 50 * MiB);
  watch(f.app, T0 + 600_000, { [NPM]: 900 * MiB });
  watch(f.app, T0 + HOUR_MS + 600_000, { [NPM]: 900 * MiB });
  expect(issuesOf(f.app, f.repoId)).toEqual([]);
});
@@ -0,0 +1,84 @@
/** The install cache hit rate (#7558): counted per contained install, and bad when it falls to half its baseline for 2 hours. */
import { afterAll, beforeAll, beforeEach, expect, test } from "bun:test";
import { HOUR_MS } from "../src/efficiency/baseline.ts";
import { hitRateLastHour, MIN_INSTALLS, noteInstall, resetInstalls } from "../src/efficiency/installs.ts";
import { hourVerdict } from "../src/efficiency/judge.ts";
import { causeOf, show } from "../src/efficiency/causes.ts";
import { meteredInstall } from "../src/checks/install.ts";
import { resetEgressTotals } from "../src/apps/egress.ts";
import { quietLogs } from "./helpers/globals.ts";
import { putSample, readSeries } from "../src/efficiency/store.ts";
import { forge, issuesOf, seed, T0, watch } from "./helpers/efficiency.ts";
quietLogs();
const HIT = "install-cache-hit-rate";
let f: Awaited<ReturnType<typeof forge>>;
beforeAll(async () => { f = await forge(); });
afterAll(() => f.done());
beforeEach(() => {
  resetInstalls();
  f.app.db.exec("DELETE FROM efficiency_sample; DELETE FROM efficiency_finding; DELETE FROM comment; DELETE FROM issue");
});
test("the counter gives the share of the last hour's installs that missed no cache, and none under 5 installs", () => {
  const t = T0 + 600_000;
  for (let i = 0; i < MIN_INSTALLS - 1; i++) noteInstall(false, t);
  expect(hitRateLastHour(t)).toBeUndefined();
  noteInstall(true, t); // 4 hits, 1 miss
  expect(hitRateLastHour(t)).toBe(0.8);
  expect(hitRateLastHour(t + HOUR_MS + 1)).toBeUndefined(); // aged out
});
test("a contained install over 1 MiB from the registry is counted as a miss", async () => {
  resetEgressTotals();
  await meteredInstall("app:t/preview", "r1", async () => 1, () => {});
  const { installsLastHour } = await import("../src/efficiency/installs.ts");
  expect(installsLastHour(Date.now())).toEqual({ installs: 1, misses: 0 });
  await meteredInstall(undefined, undefined, async () => 1, () => {}); // uncontained: not counted
  expect(installsLastHour(Date.now()).installs).toBe(1);
});
test("a hit rate at or under half its baseline is a fall; above half, or a baseline under the floor, is not", () => {
  const c = causeOf(HIT)!;
  const hour = T0;
  const base = (v: number) => new Map(Array.from({ length: 7 }, (_, d) => [hour - (d + 1) * 24 * HOUR_MS, v] as const).concat([[hour, 0]]));
  expect(hourVerdict(c, new Map(base(0.9)).set(hour, 0.45), hour)?.fell).toBe(true);
  expect(hourVerdict(c, new Map(base(0.9)).set(hour, 0.46), hour)?.fell).toBe(false);
  expect(hourVerdict(c, new Map(base(0.4)).set(hour, 0), hour)?.fell).toBe(false); // baseline under the 50% floor
  expect(hourVerdict(c, new Map(base(0.9)).set(hour, 1), hour)?.doubled).toBe(false); // a rise is never bad here
  expect(show(c, 0.456)).toBe("45.6%");
});
test("a hit rate that falls for 2 hours files one issue naming the rate, its baseline and the install path", () => {
  seed(f.app, HIT, T0, 8 * 24, () => 0.95);
  expect(watch(f.app, T0 + 600_000, { [HIT]: 0.2 }).findings).toEqual([]); // one hour is not two
  const r = watch(f.app, T0 + HOUR_MS + 600_000, { [HIT]: 0.2 });
  expect(r.findings).toHaveLength(1);
  const issues = issuesOf(f.app, f.repoId);
  expect(issues).toHaveLength(1);
  expect(issues[0]!.title).toContain("install cache hit rate");
  expect(issues[0]!.title).toContain("below");
  expect(issues[0]!.body).toContain("20.0%");
  expect(issues[0]!.body).toContain("baseline 95.0%");
  expect(issues[0]!.body).toContain("at most half");
  expect(issues[0]!.body).toContain("meteredInstall");
});
test("a steady hit rate files nothing", () => {
  seed(f.app, HIT, T0, 8 * 24, () => 0.95);
  for (let h = 0; h < 4; h++) expect(watch(f.app, T0 + h * HOUR_MS + 600_000, { [HIT]: 0.9 }).findings).toEqual([]);
  expect(issuesOf(f.app, f.repoId)).toEqual([]);
});
test("a second, higher hit rate in the same hour does not hide a fall: the lower reading stands", () => {
  seed(f.app, HIT, T0, 8 * 24, () => 0.95);
  watch(f.app, T0 + 600_000, { [HIT]: 0.2 });
  watch(f.app, T0 + HOUR_MS + 600_000, { [HIT]: 0.2 });
  watch(f.app, T0 + HOUR_MS + 1_800_000, { [HIT]: 0.9 }); // a restart's pass in the same hour, kinder
  expect(readSeries(f.app.db, HIT, T0 + HOUR_MS).get(T0 + HOUR_MS)).toBe(0.2);
  expect(issuesOf(f.app, f.repoId)).toHaveLength(1);
  // A rising cost keeps the larger of two readings in one hour.
  putSample(f.app.db, "npm-registry-bytes", T0, 10);
  putSample(f.app.db, "npm-registry-bytes", T0, 5);
  expect(readSeries(f.app.db, "npm-registry-bytes", T0).get(T0)).toBe(10);
});
@@ -0,0 +1,78 @@
/** The duty through the runner (#7558): `app` reaches it, so findings stand and a missing FORGE_REPO says why nothing was filed. */
import { afterAll, beforeAll, beforeEach, expect, test } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { HOUR_MS, hourStart } from "../src/efficiency/baseline.ts";
import { noteInstall, resetInstalls } from "../src/efficiency/installs.ts";
import { putSample } from "../src/efficiency/store.ts";
import { watch } from "../src/efficiency/watch.ts";
import { duty } from "../src/maintain/duties/efficiency_watcher.ts";
import { duties } from "../src/maintain/registry.ts";
import { startMaintain } from "../src/maintain/runner.ts";
import { latest } from "../src/maintain/runs.ts";
import { runLines } from "../src/tui/screens/maintainruns.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const HIT = "install-cache-hit-rate";
let root = "";
let app: App;
beforeAll(() => {
  root = mkdtempSync(join(tmpdir(), "forge-efficiency-run-"));
  app = createApp({ dataDir: root, port: 0 }); // no FORGE_REPO
});
afterAll(() => rmSync(root, { recursive: true, force: true }));
beforeEach(() => {
  resetInstalls();
  app.db.exec("DELETE FROM efficiency_sample; DELETE FROM maintenance_run");
});
/** A week of 95% hit rates, a bad hour before `now`, and this hour's installs all missing. */
function falling(now: number): void {
  const hour = hourStart(now);
  for (let h = 2; h <= 8 * 24; h++) putSample(app.db, HIT, hour - h * HOUR_MS, 0.95);
  putSample(app.db, HIT, hour - HOUR_MS, 0.1);
  for (let i = 0; i < 6; i++) noteInstall(true, now - 1000);
}
test("run by the runner with the app, the duty finds the fall; the admin screen lists it", async () => {
  expect(duties.map((d) => d.name)).toContain("efficiency-watcher");
  const now = Date.now();
  falling(now);
  const m = startMaintain(app, { duties: [duty], everyMs: 1e9 });
  m.stop();
  await m.tick(new Date(now));
  const [row] = latest(app.db, 1);
  expect(row!.duty).toBe("efficiency-watcher");
  expect(row!.outcome).toBe("ok");
  expect(row!.findings.length).toBeGreaterThanOrEqual(1);
  expect(JSON.stringify(row!.findings)).toContain("install cache hit rate");
  expect(row!.probes.length).toBe(row!.findings.length);
  const as = (isAdmin: boolean) => ({ user: { isAdmin }, db: app.db }) as never;
  expect(runLines(as(true)).some((l) => l.startsWith("efficiency-watcher"))).toBe(true);
  expect(runLines(as(false))).toEqual([]);
});
test("without FORGE_REPO the findings stand but the run says why nothing was filed", async () => {
  const now = Date.now();
  falling(now);
  const m = startMaintain(app, { duties: [duty], everyMs: 1e9 });
  m.stop();
  await m.tick(new Date(now));
  const [row] = latest(app.db, 1);
  expect(row!.actions.join("\n")).toContain("filed nothing: FORGE_REPO is not set");
  expect(app.db.query("SELECT COUNT(*) AS n FROM issue").get()).toEqual({ n: 0 });
});
test("a FORGE_REPO that names no repository says so", () => {
  const now = Date.now();
  falling(now);
  const other = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-efficiency-run2-")), port: 0, forgeRepo: "ghost/forge" });
  const hour = hourStart(now);
  for (let h = 2; h <= 8 * 24; h++) putSample(other.db, HIT, hour - h * HOUR_MS, 0.95);
  putSample(other.db, HIT, hour - HOUR_MS, 0.1);
  const r = watch(other, now, { [HIT]: 0.1 });
  expect(r.actions.join("\n")).toContain('names no repository on this forge');
});
@@ -0,0 +1,42 @@
/** A forge with a repository, and hourly series seeded for the efficiency watcher (#7558). */
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../../src/app.ts";
import { createRepo } from "../../src/core/repos.ts";
import { createUser } from "../../src/core/users.ts";
import { HOUR_MS } from "../../src/efficiency/baseline.ts";
import { putSample } from "../../src/efficiency/store.ts";
import { watch } from "../../src/efficiency/watch.ts";
export const MiB = 1024 ** 2;
export const DAY = 24 * HOUR_MS;
/** 2026-11-20T00:00Z: an hour boundary. */
export const T0 = Date.parse("2026-11-20T00:00:00Z");
export const NPM = "npm-registry-bytes";
export async function forge(): Promise<{ app: App; repoId: string; done(): void }> {
  const root = mkdtempSync(join(tmpdir(), "forge-efficiency-"));
  const app = createApp({ dataDir: root, port: 0, forgeRepo: "alice/forge" });
  const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
  if (!u.ok) throw new Error("user");
  const r = await createRepo(app.db, app.reposRoot, { ownerId: u.value.id, name: "forge", visibility: "public", description: "" });
  if (!r.ok) throw new Error("repo");
  return { app, repoId: r.value.id, done: () => rmSync(root, { recursive: true, force: true }) };
}
/** `hours` readings ending the hour before `end`, each `value(i)` with i counting from the first. */
export function seed(app: App, cause: string, end: number, hours: number, value: (i: number) => number): void {
  for (let i = 0; i < hours; i++) putSample(app.db, cause, end - (hours - i) * HOUR_MS, value(i));
}
export const flat = (app: App, end: number, v = 50 * MiB): void => seed(app, NPM, end, 8 * 24, () => v);
export function issuesOf(app: App, repoId: string): { id: string; number: number; title: string; state: string; body: string }[] {
  return app.db.query("SELECT id, number, title, state, body FROM issue WHERE repo_id = ?1 ORDER BY number").all(repoId) as never;
}
export const commentsOf = (app: App, issueId: string): string[] =>
  (app.db.query("SELECT body FROM comment WHERE issue_id = ?1 ORDER BY rowid").all(issueId) as { body: string }[]).map((c) => c.body);
export { watch };
		@@ -11,3 +11,14 @@ A finding must carry a probe: `{ kind: "query" \| "measurement", what, number, at
11	11	The terminal door is the palette entry "Maintenance duty runs" (`src/tui/screens/maintainruns.ts`): the same rows through the same read, offered only to a forge admin; anyone else is offered nothing and sees no rows.
12	12
13	13	Each run is bounded: a duty that has not answered in 30 seconds reads `failed: timed out` and the next duty runs (the late duty keeps its slot until it settles, so it never overlaps itself). A duty name must be lowercase words and dashes and unique, or the runner refuses to start. Each duty keeps its newest 200 rows; older ones are deleted after each run. A finding that says nothing reads `refused: a finding says nothing`. A non-admin's token reads 403 `forbidden`.
	14
	15	## efficiency-watcher (#7558)
	16
	17	Hourly, the duty records what each cost read (`efficiency_sample`, one row per cause per hour) and judges it (`src/efficiency/`):
	18
	19	- Causes (`causes.ts`): npm registry bytes received, bytes from every other destination (image pulls, git fetch and clone, apps), the machine's CPU-seconds, and the install cache hit rate. Each has a floor and, for the byte causes, an absolute ceiling. The hit rate is the share of the hour's contained installs (`meteredInstall`, counted in `installs.ts`, in memory) that fetched under 1 MiB from the registry (`NPM_MISS_BYTES`); under 5 installs in the hour there is no reading. It is a falling cause: its floor is on the baseline (a baseline under 50% is not fallen from). Not measured by cause: per-run bytes and peak memory, which have no counter to read yet.
	20	- Baseline (`baseline.ts`): the median of the same hour of the day over the last 7 days; under 3 days of history there is none, so a new forge files nothing by doubling.
	21	- Files when (`judge.ts`) an hour is at least 2x its baseline for 2 hours running (a hit rate: at most half its baseline for 2 hours running), or at or over the ceiling. The reading is the rolling last hour of the egress tally, taken when the duty runs.
	22	- One issue per cause on the forge's repository (`FORGE_REPO`, as its owner): the cause, the number, the baseline and the code path. A comment each hour it still stands; closed with a note once the cost has been back under for 24 hours. If a person closes it, the next finding opens a new one.
	23	- The series is the `efficiency` board source (admin boards), so a board can chart it.
	24	- Where an admin sees it. The run is a row on the admin's "Maintenance duty runs" screen (terminal palette; `GET /api/v1/maintenance/runs`) under `efficiency-watcher`, with each finding's probe. The hourly series is the `efficiency` source on /boards (filter `cause`, value `value`; the hit rate is 0..1). If `FORGE_REPO` is unset or names no repository, findings still show on the run and its actions say `filed nothing: <why>`.
		@@ -34,6 +34,7 @@ export const GUIDE: Readonly<Record<string, Guide>> = {
34	34	tokens: { name: "API tokens", rows: "tokens", kind: "events" },
35	35	adminActions: { name: "Admin actions", rows: "admin actions", kind: "events" },
36	36	machine: { name: "Machine readings", rows: "15-second readings", kind: "samples", value: "cpu_cores", filter: { column: "target", op: "eq", value: "forge" } },
	37	efficiency: { name: "Efficiency by cause", rows: "hourly readings", kind: "samples", value: "value", filter: { column: "cause", op: "eq", value: "npm-registry-bytes" } },
37	38	reach: { name: "Visitors and page speed", rows: "daily figures", kind: "samples", value: "value", filter: { column: "metric", op: "eq", value: "visitors" } },
38	39	app_vital: { name: "App page speed", rows: "app-days", kind: "samples", value: "load_p75" },
39	40	keeperReleases: { name: "Releases", rows: "releases", kind: "events" },
		@@ -191,6 +191,17 @@ export const SOURCES: Readonly<Record<string, Source>> = {
191	191	time: "created_at",
192	192	columns: { id: "text", kind: "text", repo_id: "text", actor_id: "text", created_at: "time" },
193	193	},
	194	// The efficiency watcher's hourly readings by cause (`efficiency/`, #7558).
	195	efficiency: {
	196	table: "efficiency_sample",
	197	owner: "admin",
	198	time: "hour",
	199	columns: { cause: "text", hour: "time", value: "number" },
	200	docs: {
	201	cause: "npm-registry-bytes, egress-other-bytes, cpu-seconds or install-cache-hit-rate (0..1)",
	202	value: "bytes received (or CPU-seconds, or share of installs that hit the cache) in the hour up to the reading",
	203	},
	204	},
194	205	// What the machine used (`boards/sampler.ts`, kept by `boards/ring.ts`):
195	206	// 15-s points for the last day, 5-min points before that, never both
196	207	// for one moment.
		@@ -18,9 +18,10 @@
18	18
19	19	import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
20	20	import { tmpdir } from "node:os";
21		import { meterEgress } from "../apps/egress.ts";
22	21	import { dirname, join } from "node:path";
	22	import { meterEgress } from "../apps/egress.ts";
23	23	import { formatBytes } from "../core/storage.ts";
	24	import { noteInstall } from "../efficiency/installs.ts";
24	25	import { err, ok, type Result } from "../kernel/result.ts";
25	26	import { fillable } from "./fillable.ts";
26	27	import { lend } from "./install_evict.ts";
		@@ -85,6 +86,7 @@ export async function meteredInstall<T>(
85	86	if (options.fetched === true) write(installFetchedLine(fetched));
86	87	const missed = npmMissLine(meter.npm());
87	88	if (missed !== undefined) write(missed);
	89	noteInstall(missed !== undefined); // the hit-rate counter the efficiency watcher reads (#7558)
88	90	}
89	91	}
90	92
		@@ -0,0 +1,1 @@
	1	23d0042136af8ee70c73f30c9b29cd3ce1e9adf1d8721b850f56d686bfaed437
		@@ -0,0 +1,16 @@
	1	// The efficiency watcher (#7558): one reading per cause per hour, and the one
	2	// finding standing per cause. Additive. Both tables are small (a few causes,
	3	// 24 rows a day each, pruned past 9 days) and read by primary key only.
	4	export default `
	5	CREATE TABLE efficiency_sample (
	6	cause TEXT NOT NULL,
	7	hour TEXT NOT NULL,
	8	value REAL NOT NULL,
	9	PRIMARY KEY (cause, hour)
	10	) WITHOUT ROWID;
	11	CREATE TABLE efficiency_finding (
	12	cause TEXT PRIMARY KEY,
	13	issue_id TEXT NOT NULL,
	14	last_bad TEXT NOT NULL
	15	) WITHOUT ROWID;
	16	`;
		@@ -0,0 +1,28 @@
	1	/** The baseline (#7558): the median of the same hour of the day over the last seven days. Plain data in, a number out. */
	2
	3	export const HOUR_MS = 3_600_000;
	4	export const BASELINE_DAYS = 7;
	5	/** Fewer days of history than this and there is no baseline: a new forge files nothing by doubling. */
	6	export const MIN_DAYS = 3;
	7
	8	/** hour start (ms) → value, for one cause. */
	9	export type Series = ReadonlyMap<number, number>;
	10
	11	export const hourStart = (ms: number): number => Math.floor(ms / HOUR_MS) * HOUR_MS;
	12
	13	export function median(values: readonly number[]): number \| undefined {
	14	if (values.length === 0) return undefined;
	15	const s = [...values].sort((a, b) => a - b);
	16	const m = s.length >> 1;
	17	return s.length % 2 === 1 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
	18	}
	19
	20	/** Median of the readings at `hour` minus 1..7 days; undefined with fewer than MIN_DAYS of them. */
	21	export function baselineAt(series: Series, hour: number): number \| undefined {
	22	const same: number[] = [];
	23	for (let d = 1; d <= BASELINE_DAYS; d++) {
	24	const v = series.get(hour - d * 24 * HOUR_MS);
	25	if (v !== undefined) same.push(v);
	26	}
	27	return same.length < MIN_DAYS ? undefined : median(same);
	28	}
		@@ -0,0 +1,74 @@
	1	/** What the efficiency watcher measures (#7558): each cost by cause, its unit, its floor and ceiling, and the code path that starts it. Plain data. */
	2
	3	export interface Cause {
	4	/** Lowercase words and dashes; the sample's `cause`. */
	5	readonly id: string;
	6	readonly label: string;
	7	/** "bytes", "seconds" or "ratio" (0 to 1): the unit every number of this cause is in, hourly. */
	8	readonly unit: "bytes" \| "seconds" \| "ratio";
		sentinelcrew 4d ago Comment says bytes or seconds; the type also has "ratio". Update.
	9	/** "rising" is bad when it doubles; "falling" (a hit rate) is bad when it halves. */
	10	readonly direction: "rising" \| "falling";
	11	/**
	12	* Rising: an hour below this is never "doubled" (a baseline of nothing makes any byte a doubling).
	13	* Falling: a baseline below this is never "fallen from" (a cache that rarely hit has nothing to lose).
	14	*/
	15	readonly floor: number;
	16	/** An hour at or above this files at once, baseline or not. */
	17	readonly ceiling: number \| undefined;
	18	/** Where the cost starts, named in the finding. */
	19	readonly path: string;
	20	}
	21
	22	const MiB = 1024 ** 2;
	23	const GiB = 1024 ** 3;
	24
	25	export const CAUSES: readonly Cause[] = [
	26	{
	27	id: "npm-registry-bytes",
	28	label: "npm registry bytes received",
	29	unit: "bytes",
	30	direction: "rising",
	31	floor: 256 * MiB,
	32	ceiling: 4 * GiB,
	33	path: "an install step (`bun install` in `src/checks/service.ts`, an app's install in `src/apps/`) reaching registry.npmjs.org:443 through the egress proxy (`src/apps/egress.ts`, `NPM_REGISTRY`); a cold or unshared bun cache starts it",
	34	},
	35	{
	36	id: "egress-other-bytes",
	37	label: "bytes received from every other destination (image pulls, git fetch and clone, apps)",
	38	unit: "bytes",
	39	direction: "rising",
	40	floor: 512 * MiB,
	41	ceiling: 10 * GiB,
	42	path: "a cell or app reaching a host other than the registry through the egress proxy (`src/apps/egress.ts`, `egressTotals`); the destination is in the forge's /metrics `forge_egress_received_bytes_total`",
	43	},
	44	{
	45	id: "cpu-seconds",
	46	label: "CPU-seconds used by the forge's machine",
	47	unit: "seconds",
	48	direction: "rising",
	49	floor: 900,
	50	ceiling: undefined,
	51	path: "whatever ran hot: the 15 s sampler (`src/boards/sampler.ts`) names cpu per cell label in the `machine` source",
	52	},
	53	{
	54	id: "install-cache-hit-rate",
	55	label: "install cache hit rate (installs that fetched under 1 MiB from the npm registry)",
	56	unit: "ratio",
	57	direction: "falling",
	58	floor: 0.5,
	59	ceiling: undefined,
	60	path: "a contained install (`meteredInstall` in `src/checks/install.ts`) fetching over 1 MiB from the registry because the shared cache (`prefillInstallCache`, `checkInstallCache`) was cold, evicted (`src/checks/install_evict.ts`) or not filled; counted in `src/efficiency/installs.ts`",
	61	},
	62	];
	63
	64	export const causeOf = (id: string): Cause \| undefined => CAUSES.find((c) => c.id === id);
	65
	66	export function show(c: Cause, n: number): string {
	67	if (c.unit === "ratio") return `${(n * 100).toFixed(1)}%`;
	68	if (c.unit === "seconds") return `${Math.round(n)} CPU-seconds`;
	69	const units = ["B", "KiB", "MiB", "GiB", "TiB"];
	70	let v = n;
	71	let i = 0;
	72	while (v >= 1024 && i < units.length - 1) (v /= 1024), i++;
	73	return `${i === 0 ? v : v.toFixed(2)} ${units[i]}`;
	74	}
		@@ -0,0 +1,32 @@
	1	/** The words of a finding and its comments (#7558): the cause, the number, the baseline, the code path. */
	2
	3	import { show, type Cause } from "./causes.ts";
	4	import type { HourVerdict, Why } from "./judge.ts";
	5
	6	const at = (ms: number): string => `${new Date(ms).toISOString().slice(0, 13)}:00 UTC`;
	7
	8	export const titleOf = (c: Cause): string => `Efficiency: ${c.label} is far ${c.direction === "falling" ? "below" : "above"} its usual`;
	9
	10	export function numbers(c: Cause, v: HourVerdict, why: Why): string {
	11	const base = v.baseline === undefined ? "no baseline yet" : `baseline ${show(c, v.baseline)} (median of this hour over the last 7 days)`;
	12	const rule =
	13	why === "ceiling"
	14	? `at or over the ceiling of ${show(c, c.ceiling ?? 0)}`
	15	: why === "fell"
	16	? "at most half its baseline for 2 hours running"
	17	: "at least 2x its baseline for 2 hours running";
	18	return `${show(c, v.value)} in the hour of ${at(v.hour)}; ${base}; ${rule}.`;
	19	}
	20
	21	export function bodyOf(c: Cause, v: HourVerdict, why: Why): string {
	22	return (
	23	`The efficiency watcher (duty \`efficiency-watcher\`) found ${c.label}: ${numbers(c, v, why)}\n\n` +
	24	`Code path that starts the cost: ${c.path}.\n\n` +
	25	`This issue stands while the cost does: it gets a comment each hour it is still bad, and is closed with a note once it has been back under for 24 hours. ` +
	26	`The hourly series is the \`efficiency\` board source.`
	27	);
	28	}
	29
	30	export const commentOf = (c: Cause, v: HourVerdict, why: Why): string => `Still bad: ${numbers(c, v, why)}`;
	31
	32	export const closingNote = (c: Cause): string => `${c.label} has been back under its baseline and ceiling for 24 hours. Closing; a new finding opens if it returns.`;
		@@ -0,0 +1,37 @@
	1	/** The install cache counter (#7558): each contained install, and whether it missed the shared cache. In memory, the last hour only. */
	2
	3	import { HOUR_MS } from "./baseline.ts";
	4
	5	/** Fewer installs than this in the hour and there is no hit rate: one install is not a rate. */
	6	export const MIN_INSTALLS = 5;
	7
	8	const seen: { at: number; missed: boolean }[] = [];
	9
	10	/** One contained install finished; `missed` when the registry sent more than `NPM_MISS_BYTES` (`checks/install.ts`). */
	11	export function noteInstall(missed: boolean, now: number = Date.now()): void {
	12	seen.push({ at: now, missed });
	13	prune(now);
	14	}
	15
	16	function prune(now: number): void {
	17	let n = 0;
	18	while (n < seen.length && seen[n]!.at <= now - HOUR_MS) n++;
	19	if (n > 0) seen.splice(0, n);
	20	}
	21
	22	/** Installs in the hour up to `now` and how many missed. */
	23	export function installsLastHour(now: number): { installs: number; misses: number } {
	24	prune(now);
	25	return { installs: seen.length, misses: seen.filter((s) => s.missed).length };
	26	}
	27
	28	/** Share of the last hour's installs that hit the cache, 0..1; undefined under MIN_INSTALLS. */
	29	export function hitRateLastHour(now: number): number \| undefined {
	30	const { installs, misses } = installsLastHour(now);
	31	return installs < MIN_INSTALLS ? undefined : (installs - misses) / installs;
	32	}
	33
	34	/** For tests: forget every install. */
	35	export function resetInstalls(): void {
	36	seen.length = 0;
	37	}