@manyoars/oars 0.3.0 → 0.4.0

package/dist/telemetry/health.js

@@ -0,0 +1,108 @@
+// What the nightly run tells telemetry about the health of an install: a snapshot of the session store (counts, sizes, verify results, the versions it
+// holds) and what the run cost. Counts, bytes, and closed words only; the schema checks them again before anything reaches the spool.
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CAPTURE_VERSION, OLDEST_READABLE_CAPTURE } from '../sessions/schema.js';
+import { readSteps } from '../sessions/steps.js';
+import { frozenSessions, loadStore, paths, readSkeletons } from '../sessions/store.js';
+import { LITERAL, publicModel, publicVersion } from '../sessions/public-vocabulary.js';
+import { verifyAll, verifyCaptured } from '../sessions/verify.js';
+import { emitEvent, recordsEvents } from './emit.js';
+import { spoolEvents } from './read-events.js';
+const MAX_LIST = 32;
+const OTHER = 'other';
+const WEEK_MS = 7 * 86_400_000;
+/**
+ * The distinct values seen, each kept when the pool wire's own public vocabulary admits it and written as `other` when it does not, sorted with `other`
+ * last. More than the schema's list length folds the tail into `other`.
+ */
+export const closedList = (values, kind) => {
+    const visible = kind === 'version' ? publicVersion : publicModel;
+    const kept = new Set();
+    let other = false;
+    for (const value of values) {
+        const shown = visible(value);
+        if (shown === null || shown === LITERAL || shown !== value)
+            other = true;
+        else
+            kept.add(value);
+    }
+    const sorted = [...kept].sort();
+    const room = MAX_LIST - 1;
+    if (sorted.length > room)
+        return [...sorted.slice(0, room), OTHER];
+    return other ? [...sorted, OTHER] : sorted;
+};
+/** The distinct whole-number versions among the stamps, ascending; a stamp that is not a whole number names no version and is left out. */
+export const versionsHeld = (stamps) => [...new Set(stamps.map(Number).filter((stamp) => Number.isSafeInteger(stamp) && stamp >= 0))].sort((a, b) => a - b).slice(-MAX_LIST);
+/** Every byte under a folder; a folder that is not there holds none. */
+const bytesUnder = async (dir) => {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return 0;
+        throw error;
+    }
+    let total = 0;
+    for (const entry of entries)
+        total += entry.isDirectory() ? await bytesUnder(join(dir, entry.name)) : (await stat(join(dir, entry.name))).size;
+    return total;
+};
+/** The bytes the last seven days of sends put on the wire, read from telemetry's own `wire-send` events: nothing is asked of the pool. */
+const egressBytes = (dir, now) => spoolEvents(dir, 'wire-send').reduce((total, { at, data }) => (data.sent === 1 && typeof data.bytes === 'number' && Date.parse(at) >= now - WEEK_MS ? total + data.bytes : total), 0);
+/** The extractor version each pipeline step last ran at: the log is append-only, so older rows name versions the store no longer holds. A tie on `at` goes to the later row. */
+const lastExtractorVersions = (steps) => {
+    const latest = new Map();
+    for (const step of steps) {
+        const held = latest.get(step.step);
+        if (held === undefined || Date.parse(step.at) >= Date.parse(held.at))
+            latest.set(step.step, step);
+    }
+    return [...latest.values()].map((step) => step.ev);
+};
+const storeFields = async (runtime) => {
+    const { storeDir } = runtime;
+    const { skeletons, unreadable } = await readSkeletons(storeDir, undefined, true);
+    const store = await loadStore(storeDir);
+    const steps = await readSteps(storeDir);
+    const captured = [...store.sessions, ...store.subagents];
+    const frozen = await frozenSessions(runtime, captured.filter((session) => Number(session.cv) >= OLDEST_READABLE_CAPTURE && Number(session.cv) < Number(CAPTURE_VERSION)));
+    const results = [...verifyAll(skeletons, skeletons), ...verifyCaptured(captured, store.tools, frozen)];
+    return {
+        sessions: store.sessions.length,
+        subagents: store.subagents.length,
+        skeletons: skeletons.length,
+        unparseable: unreadable + captured.reduce((sum, session) => sum + session.badLines, 0),
+        rawBytes: await bytesUnder(paths(storeDir).raw),
+        verifyChecked: results.length,
+        verifyFailed: results.filter((result) => result.violations > 0).length,
+        // What the store holds: the `cv` of each captured session and the `ev` each pipeline step last ran at. A store with a session behind this build lists two.
+        captureVersions: versionsHeld(captured.map((session) => session.cv)),
+        extractorVersions: versionsHeld(lastExtractorVersions(steps)),
+        harnessVersions: closedList(captured.flatMap((session) => session.versions), 'version'),
+        models: closedList(captured.flatMap((session) => Object.keys(session.models)), 'model'),
+    };
+};
+/** The store-health event of one nightly run. A store that cannot be read is recorded as that and nothing else; it never stops the run. */
+export const recordStoreHealth = async (telemetry, runtime) => {
+    // The pass reads every skeleton and stats every raw file, so an install with telemetry off must not start it.
+    if (!recordsEvents(telemetry))
+        return;
+    try {
+        const fields = await storeFields(runtime);
+        // The outbox is an extra: a folder that cannot be read leaves the two figures out and the snapshot stands.
+        const extras = await bytesUnder(join(runtime.storeDir, 'pool-outbox')).then((outboxBytes) => ({ outboxBytes, egressBytes: egressBytes(telemetry.telemetry?.dir ?? '', telemetry.now()) }), () => ({}));
+        emitEvent(telemetry, 'store-health', { ...fields, ...extras });
+    }
+    catch {
+        emitEvent(telemetry, 'store-health', { readFailed: 1 });
+    }
+};
+/** What a nightly run cost: the whole run, the deposit's parse, the process's peak memory, and whether it failed. */
+export const recordRunCost = (telemetry, cost) => {
+    const peak = telemetry.peakRssMb ?? (() => Math.round(process.resourceUsage().maxRSS / 1024));
+    emitEvent(telemetry, 'run-cost', { totalMs: Math.max(0, cost.totalMs), parseMs: Math.max(0, cost.parseMs), peakRssMb: peak(), failed: cost.failed ? 1 : 0 });
+};

package/dist/telemetry/hook-emit.d.ts

@@ -0,0 +1,4 @@
+import { type Emit } from './emit.js';
+/** The version in the package.json at `manifest`; `0.0.0` when it cannot be read (the schema writes a version it cannot read as `unknown`). */
+export declare const versionAt: (manifest: URL) => string;
+export declare const hookEmitter: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string, manifest: URL, now: () => number) => Emit;

package/dist/telemetry/hook-emit.js

@@ -0,0 +1,18 @@
+// The emitter a hook process builds for itself. A hook never loads the CLI (`main.ts` reads the version and the folders), so this reads the same two things for itself:
+// the config folder the CLI uses, and the version in this package's `package.json`, read only when an event is about to be written.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultConfigDir } from '../credentials.js';
+import { emitFor } from './emit.js';
+/** The version in the package.json at `manifest`; `0.0.0` when it cannot be read (the schema writes a version it cannot read as `unknown`). */
+export const versionAt = (manifest) => {
+    try {
+        const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+        const version = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'version') : undefined;
+        return typeof version === 'string' ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+export const hookEmitter = (env, platform, home, manifest, now) => emitFor({ env, telemetry: { dir: join(defaultConfigDir(env, platform, home), 'oars', 'telemetry'), platform }, version: () => versionAt(manifest), now });

package/dist/telemetry/measures.d.ts

@@ -0,0 +1,32 @@
+/** A latency in a cell, or a yes (1) or no (0) that a rate is made from. */
+export type Kind = 'latency' | 'rate';
+export interface Measure {
+    metric: string;
+    /** What the value groups by: the harness and harness version a hook ran under (`claude-code/2.1.5`), or the oars version for a command. */
+    dimension: 'harnessVersion' | 'cli';
+    value: string;
+    kind: Kind;
+    /** Milliseconds for a latency; 1 or 0 for a rate. */
+    x: number;
+}
+/** The windows the report shows and the pool serves, in days. */
+export declare const WINDOWS: readonly number[];
+/** The hooks that exist; any other name in a batch is not measured. */
+export declare const HOOK_NAMES: readonly string[];
+export declare const OTHER = "other";
+export declare const UNRECORDED = "unrecorded";
+/** What one event measures; an event of a type nothing measures, or that is not an object, measures nothing. */
+export declare const measuresOf: (event: unknown) => Measure[];
+/** Every cell is named by these three together. */
+export declare const cellKey: (measure: Pick<Measure, "metric" | "dimension" | "value">) => string;
+/**
+ * The bucket edges a latency histogram counts in, each 1.5 times the one before (1, 2, 3, 4, 6, 9, ...) up to a day. The pool keeps a histogram, not the latencies, so its percentile is the
+ * upper edge of the bucket that holds it: within a factor of 1.5 of the true one.
+ */
+export declare const LATENCY_EDGES: readonly number[];
+/** The index of the first edge at or above the latency. */
+export declare const bucketOf: (milliseconds: number) => number;
+/** The p-th percentile (0 to 1) of a histogram given as [bucket index, count] pairs, as that bucket's upper edge. */
+export declare const histogramPercentile: (buckets: readonly (readonly [number, number])[], p: number) => number;
+/** The nearest-rank p-th percentile (0 to 1) of numbers; 0 for none. */
+export declare const percentile: (values: readonly number[], p: number) => number;

package/dist/telemetry/measures.js

@@ -0,0 +1,128 @@
+// What telemetry measures, in one place: the CLI's own report and the pool's rollup both turn an event into the same `Measure`s, so a user's number and the fleet's are the same number.
+// A measure is one observation in a cell: a latency in milliseconds, or a yes/no that rates are made from. The cell is (metric, dimension, value): `hook.pre-tool.latency` at harness
+// `claude-code`, version `2.1.5`. The reader is tolerant on purpose: the pool reads batches kept whole from any client, so a value that does not fit is skipped, never trusted.
+import { isHarness } from '../sessions/pool-wire.js';
+/** The windows the report shows and the pool serves, in days. */
+export const WINDOWS = [7, 30];
+const DAY_MS = 86_400_000;
+/** The hooks that exist; any other name in a batch is not measured. */
+export const HOOK_NAMES = ['session-start', 'prompt', 'pre-tool', 'post-tool', 'stop', 'nightly', 'gate'];
+/** A group value as the program writes it: a version or a word, short, with no space, slash, or quote. Anything else is `other`. */
+const VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+const COMMAND = /^[a-z][A-Za-z0-9-]{0,31}$/;
+export const OTHER = 'other';
+export const UNRECORDED = 'unrecorded';
+const valueOf = (raw) => {
+    if (raw === undefined)
+        return UNRECORDED;
+    return typeof raw === 'string' && VALUE.test(raw) ? raw : OTHER;
+};
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const fieldOf = (value, key) => (isObject(value) ? Reflect.get(value, key) : undefined);
+/** A whole number of milliseconds a day long at most, or undefined. */
+const millis = (value) => (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= DAY_MS ? value : undefined);
+const latency = (metric, dimension, value, x) => ({ metric, dimension, value, kind: 'latency', x });
+const rate = (metric, dimension, value, yes) => ({ metric, dimension, value, kind: 'rate', x: yes ? 1 : 0 });
+/**
+ * The value of a hook cell: the harness and its version, `claude-code/2.1.5`, so one version number under two harnesses is two cells. A harness off the closed list is `other`; an event written
+ * before the field existed has none and reads `unrecorded`, never dropped.
+ */
+const hookCellOf = (harness, version) => {
+    const named = harness === undefined ? UNRECORDED : typeof harness === 'string' && isHarness(harness) ? harness : OTHER;
+    return `${named}/${valueOf(version)}`;
+};
+/** The measures of a `hook` event: its latency, and whether it found something. A hook that failed is neither a hit nor a miss. */
+const hookMeasures = (data) => {
+    const name = fieldOf(data, 'name');
+    if (typeof name !== 'string' || !HOOK_NAMES.includes(name))
+        return [];
+    const version = hookCellOf(fieldOf(data, 'harness'), fieldOf(data, 'harnessVersion'));
+    const found = [];
+    const took = millis(fieldOf(data, 'latencyMs'));
+    if (took !== undefined)
+        found.push(latency(`hook.${name}.latency`, 'harnessVersion', version, took));
+    const outcome = fieldOf(data, 'outcome');
+    // `held` found something and held it back for the unexposed arm, so it counts as a find.
+    if (outcome === 'hit' || outcome === 'held')
+        found.push(rate(`hook.${name}.hit`, 'harnessVersion', version, true));
+    else if (outcome === 'miss')
+        found.push(rate(`hook.${name}.hit`, 'harnessVersion', version, false));
+    return found;
+};
+/** The measures of a `command` event: how long it took, and whether it failed, under the first name of its path. */
+const commandMeasures = (event, data) => {
+    const path = fieldOf(data, 'path');
+    const first = Array.isArray(path) && typeof path[0] === 'string' && COMMAND.test(path[0]) ? path[0] : 'none';
+    const version = valueOf(fieldOf(event, 'cli'));
+    const found = [];
+    const took = millis(fieldOf(data, 'durationMs'));
+    if (took !== undefined)
+        found.push(latency(`command.${first}.latency`, 'cli', version, took));
+    const exit = fieldOf(data, 'exitCode');
+    if (typeof exit === 'number' && Number.isSafeInteger(exit) && exit >= 0 && exit <= 255)
+        found.push(rate(`command.${first}.failure`, 'cli', version, exit !== 0));
+    return found;
+};
+/** The measures of a `store-health` event: whether the nightly could read the store, and whether it found a session that does not verify. */
+const storeMeasures = (event, data) => {
+    const version = valueOf(fieldOf(event, 'cli'));
+    const unread = fieldOf(data, 'readFailed') === 1;
+    const found = [rate('store.readFailure', 'cli', version, unread)];
+    const failed = fieldOf(data, 'verifyFailed');
+    if (!unread && typeof failed === 'number' && Number.isSafeInteger(failed) && failed >= 0)
+        found.push(rate('store.verifyFailure', 'cli', version, failed > 0));
+    return found;
+};
+/** What one event measures; an event of a type nothing measures, or that is not an object, measures nothing. */
+export const measuresOf = (event) => {
+    const type = fieldOf(event, 'type');
+    const data = fieldOf(event, 'data');
+    switch (type) {
+        case 'hook':
+            return hookMeasures(data);
+        case 'command':
+            return commandMeasures(event, data);
+        case 'store-health':
+            return storeMeasures(event, data);
+        default:
+            return [];
+    }
+};
+/** Every cell is named by these three together. */
+export const cellKey = (measure) => `${measure.metric}\u0000${measure.dimension}\u0000${measure.value}`;
+/**
+ * The bucket edges a latency histogram counts in, each 1.5 times the one before (1, 2, 3, 4, 6, 9, ...) up to a day. The pool keeps a histogram, not the latencies, so its percentile is the
+ * upper edge of the bucket that holds it: within a factor of 1.5 of the true one.
+ */
+export const LATENCY_EDGES = (() => {
+    const edges = [];
+    for (let step = 0;; step += 1) {
+        const edge = Math.ceil(1.5 ** step);
+        if (edges.at(-1) !== edge)
+            edges.push(edge);
+        if (edge >= DAY_MS)
+            return edges;
+    }
+})();
+/** The index of the first edge at or above the latency. */
+export const bucketOf = (milliseconds) => LATENCY_EDGES.findIndex((edge) => milliseconds <= edge);
+/** The p-th percentile (0 to 1) of a histogram given as [bucket index, count] pairs, as that bucket's upper edge. */
+export const histogramPercentile = (buckets, p) => {
+    const sorted = [...buckets].sort((a, b) => a[0] - b[0]);
+    const total = sorted.reduce((sum, [, count]) => sum + count, 0);
+    const target = Math.max(1, Math.ceil(p * total));
+    let seen = 0;
+    for (const [index, count] of sorted) {
+        seen += count;
+        if (seen >= target)
+            return LATENCY_EDGES[index] ?? DAY_MS;
+    }
+    return 0;
+};
+/** The nearest-rank p-th percentile (0 to 1) of numbers; 0 for none. */
+export const percentile = (values, p) => {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))] ?? 0;
+};

package/dist/telemetry/observe.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+import type { RunDeps } from '../cli.js';
+import type { ExitCode } from '../errors.js';
+export interface Observed {
+    /** The command path, such as `['pool', 'fetch']`; empty when no command ran (`--help`, `--version`, a usage error). */
+    path: string[];
+    /** The long names (as commander keys them) of the options given on the command line. */
+    flags: string[];
+}
+/** Called by commander just before an action runs. */
+export declare const observeCommand: (observed: Observed, action: Command) => void;
+/** Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. */
+export declare const finishTelemetry: (deps: RunDeps, argv: string[], observed: Observed, startedAt: number, exit: ExitCode) => void;

package/dist/telemetry/observe.js

@@ -0,0 +1,51 @@
+import { consentOf, markNoticeShown, NOTICE } from './consent.js';
+import { recordEvent } from './record.js';
+import { startDailySend } from './send.js';
+import { errorClassOf } from './schema.js';
+const pathOf = (command) => {
+    const names = [];
+    let step = command;
+    // The root program has no parent and is not part of the path.
+    while (step.parent !== null) {
+        names.unshift(step.name());
+        step = step.parent;
+    }
+    return names;
+};
+/** Called by commander just before an action runs. */
+export const observeCommand = (observed, action) => {
+    observed.path = pathOf(action);
+    const given = action.optsWithGlobals();
+    observed.flags = Object.keys(given).filter((key) => action.getOptionValueSourceWithGlobals(key) === 'cli');
+};
+const isHook = (argv, observed) => {
+    const gateHook = (words) => words[0] === 'gate' && words[1] === 'hook';
+    return gateHook(observed.path) || gateHook(argv);
+};
+/** Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. */
+export const finishTelemetry = (deps, argv, observed, startedAt, exit) => {
+    try {
+        const runtime = deps.telemetry;
+        if (runtime === undefined)
+            return;
+        const consent = consentOf(deps.env, runtime.dir);
+        if (!consent.enabled)
+            return;
+        if (!consent.noticeShown && !isHook(argv, observed) && markNoticeShown(runtime.dir, deps.now))
+            deps.io.stderr(`${NOTICE}\n`);
+        const errorClass = errorClassOf(exit);
+        recordEvent({ ...runtime, version: deps.version, now: deps.now }, 'command', {
+            path: observed.path,
+            flags: observed.flags,
+            durationMs: Math.max(0, deps.now() - startedAt),
+            exitCode: exit,
+            ...(errorClass === undefined ? {} : { errorClass }),
+        });
+        // Never from a hook: a hook has a time budget, and the send is for the nightly task and the commands a person runs.
+        if (!isHook(argv, observed))
+            startDailySend(runtime, deps.env, deps.now());
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};

package/dist/telemetry/read-events.d.ts

@@ -0,0 +1,9 @@
+export interface SpoolEvent {
+    type: string;
+    at: string;
+    data: {
+        [field: string]: unknown;
+    };
+}
+/** Every spooled event, oldest first, or only those of `type`. */
+export declare const spoolEvents: (dir: string, type?: string) => SpoolEvent[];

package/dist/telemetry/read-events.js

@@ -0,0 +1,17 @@
+// The spool's events read back as typed values, by type: for the nightly figures that sum earlier events and for the tests that check what was written.
+// A line that is not an event is left out.
+import { readSpool } from './spool.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const eventOf = (line) => {
+    try {
+        const parsed = JSON.parse(line);
+        if (isRecord(parsed) && typeof parsed.type === 'string' && typeof parsed.at === 'string' && isRecord(parsed.data))
+            return { type: parsed.type, at: parsed.at, data: parsed.data };
+    }
+    catch {
+        // Not JSON: not an event.
+    }
+    return undefined;
+};
+/** Every spooled event, oldest first, or only those of `type`. */
+export const spoolEvents = (dir, type) => readSpool(dir).flatMap((line) => eventOf(line) ?? []).filter((event) => type === undefined || event.type === type);

package/dist/telemetry/record.d.ts

@@ -0,0 +1,17 @@
+/** Where telemetry keeps its folder; absent from a run, nothing is recorded. */
+export interface TelemetryRuntime {
+    /** `<config>/oars/telemetry`. */
+    dir: string;
+    platform: NodeJS.Platform;
+    /** Starts the detached send (`spawnDetachedSend`); only `main.ts` supplies it, so a run without one never sends. */
+    spawnSend?: (dir: string) => void;
+}
+export interface RecordContext extends TelemetryRuntime {
+    /** The CLI's version. */
+    version: string;
+    /** Epoch milliseconds. */
+    now: () => number;
+    /** The spool's byte cap per file; absent means `SPOOL_CAP_BYTES`. */
+    capBytes?: number;
+}
+export declare const recordEvent: (context: RecordContext, type: string, fields: object) => void;

package/dist/telemetry/record.js

@@ -0,0 +1,26 @@
+// Records one event: closed schema, then the spool. It never throws and returns nothing, so a command's exit code and output cannot depend on it.
+import { SCHEMA_VERSION, sanitize } from './schema.js';
+import { appendLine, installId } from './spool.js';
+const OS = ['win32', 'darwin', 'linux'];
+const VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]{1,32})?$/;
+export const recordEvent = (context, type, fields) => {
+    try {
+        const checked = sanitize(type, fields);
+        if (checked === undefined)
+            return;
+        const event = {
+            v: SCHEMA_VERSION,
+            id: installId(context.dir),
+            at: new Date(context.now()).toISOString(),
+            type,
+            cli: VERSION.test(context.version) ? context.version : 'unknown',
+            os: OS.includes(context.platform) ? context.platform : 'other',
+            ...(checked.dropped > 0 ? { dropped: checked.dropped } : {}),
+            data: checked.data,
+        };
+        appendLine(context.dir, JSON.stringify(event), context.capBytes);
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};

package/dist/telemetry/report.d.ts

@@ -0,0 +1,77 @@
+import { type Kind, type Measure } from './measures.js';
+/** The fleet's number for one cell: percentiles of the fleet's latency, or the median install's rate. */
+export interface FleetNumbers {
+    p50: number;
+    p95?: number;
+}
+export interface FleetCell extends FleetNumbers {
+    metric: string;
+    dimension: Measure['dimension'];
+    value: string;
+    kind: Kind;
+}
+export interface OwnCell {
+    metric: string;
+    dimension: Measure['dimension'];
+    value: string;
+    kind: Kind;
+    /** Observations in the window. */
+    n: number;
+    p50?: number;
+    p95?: number;
+    /** For a rate: the share of the user's observations that were a yes. */
+    rate?: number;
+    fleet?: FleetNumbers;
+}
+export interface StoreSnapshot {
+    at: string;
+    readFailed: boolean;
+    sessions?: number;
+    subagents?: number;
+    skeletons?: number;
+    unparseable?: number;
+    verifyChecked?: number;
+    verifyFailed?: number;
+    rawBytes?: number;
+}
+/**
+ * The user's own cells over the last `days`, ordered by metric and then value; with `asOf`, over the `days` ending with that day instead. A latency is counted in the same buckets the fleet's is,
+ * so the user's p50 and the fleet's are the same kind of number (the bucket's upper edge) and a spool identical to a fleet cell reads equal to it.
+ */
+export declare const ownCells: (lines: readonly string[], now: number, days: number, asOf?: string) => OwnCell[];
+/** The newest store-health snapshot in the window: its counts as the nightly recorded them. */
+export declare const latestStore: (lines: readonly string[], now: number, days: number) => StoreSnapshot | undefined;
+/** The user's cells with the fleet's number put on each cell the fleet serves; the fleet is `undefined` when no read answered. */
+export declare const besideFleet: (own: readonly OwnCell[], fleet: readonly FleetCell[] | undefined) => OwnCell[];
+export interface FleetWindow {
+    days: number;
+    cells: FleetCell[];
+}
+export type FleetRead = {
+    status: 'not-configured';
+} | {
+    status: 'unavailable';
+    server?: string;
+    reason: string;
+} | {
+    status: 'answered';
+    server: string;
+    asOf: string;
+    floor: number;
+    windows: FleetWindow[];
+};
+/**
+ * The fleet's numbers from the pool server in `OARS_POOL_URL`, or why there are none. The request is a bare GET: it names no install and sends no credential, cookie, or event.
+ * Anything wrong, a refusal, a timeout, or an answer of the wrong shape, comes back as `unavailable`; it never fails the report.
+ */
+export declare const readFleet: (env: NodeJS.ProcessEnv) => Promise<FleetRead>;
+export interface Report {
+    windows: {
+        days: number;
+        cells: OwnCell[];
+    }[];
+    store: StoreSnapshot | undefined;
+    fleet: FleetRead;
+}
+export declare const reportOf: (lines: readonly string[], now: number, fleet: FleetRead) => Report;
+export declare const textOf: (report: Report, dir: string) => string;