@manyoars/oars 0.2.0 → 0.4.0

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;

package/dist/telemetry/report.js

@@ -0,0 +1,188 @@
+// `oars telemetry report`: what telemetry measured about the user's own use, from the spool on this machine, beside the fleet's number for the same cell when a pool server is configured and answers.
+// The own numbers need no server and no account. The fleet read is a plain GET that carries nothing of the user's: no credential, no install id, no event. Nothing here writes the spool.
+import { CliError } from '../errors.js';
+import { bucketOf, cellKey, histogramPercentile, measuresOf, WINDOWS } from './measures.js';
+const DAY_MS = 86_400_000;
+const FLEET_TIMEOUT_MS = 10_000;
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const fieldOf = (value, key) => (isObject(value) ? Reflect.get(value, key) : undefined);
+/** The spool's events that parse and carry a time. A line that is not an event is skipped; the spool is the user's file and may hold anything. */
+const eventsOf = (lines) => lines.flatMap((line) => {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return [];
+    }
+    const raw = fieldOf(event, 'at');
+    const at = typeof raw === 'string' ? Date.parse(raw) : Number.NaN;
+    return Number.isNaN(at) ? [] : [{ at, event }];
+});
+const within = (parsed, now, days) => parsed.filter(({ at }) => at >= now - days * DAY_MS && at <= now + DAY_MS);
+/** The fleet's window ends with the day it is as of, a whole UTC day: the user's own window must end there too, or a cell reported only today reads as one the fleet does not serve. */
+const upToDay = (parsed, days, asOf) => {
+    const end = Date.parse(`${asOf}T00:00:00Z`) + DAY_MS;
+    return Number.isNaN(end) ? [] : parsed.filter(({ at }) => at >= end - days * DAY_MS && at < end);
+};
+/**
+ * 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 const ownCells = (lines, now, days, asOf) => {
+    const groups = new Map();
+    const parsed = eventsOf(lines);
+    for (const { event } of asOf === undefined ? within(parsed, now, days) : upToDay(parsed, days, asOf)) {
+        for (const measure of measuresOf(event)) {
+            const key = cellKey(measure);
+            const group = groups.get(key) ?? { head: measure, xs: [] };
+            group.xs.push(measure.x);
+            groups.set(key, group);
+        }
+    }
+    return [...groups.values()]
+        .map(({ head, xs }) => {
+        const { metric, dimension, value, kind } = head;
+        if (kind === 'rate')
+            return { metric, dimension, value, kind, n: xs.length, rate: xs.reduce((sum, x) => sum + x, 0) / xs.length };
+        const buckets = new Map();
+        for (const x of xs)
+            buckets.set(bucketOf(x), (buckets.get(bucketOf(x)) ?? 0) + 1);
+        return { metric, dimension, value, kind, n: xs.length, p50: histogramPercentile([...buckets], 0.5), p95: histogramPercentile([...buckets], 0.95) };
+    })
+        .sort((a, b) => a.metric.localeCompare(b.metric) || a.value.localeCompare(b.value));
+};
+const COUNTS = ['sessions', 'subagents', 'skeletons', 'unparseable', 'verifyChecked', 'verifyFailed', 'rawBytes'];
+/** The newest store-health snapshot in the window: its counts as the nightly recorded them. */
+export const latestStore = (lines, now, days) => {
+    const newest = within(eventsOf(lines), now, days)
+        .filter(({ event }) => fieldOf(event, 'type') === 'store-health')
+        .sort((a, b) => b.at - a.at)[0];
+    if (newest === undefined)
+        return undefined;
+    const data = fieldOf(newest.event, 'data');
+    const field = (name) => fieldOf(data, name);
+    const snapshot = { at: new Date(newest.at).toISOString(), readFailed: field('readFailed') === 1 };
+    for (const name of COUNTS) {
+        const found = field(name);
+        if (typeof found === 'number' && Number.isSafeInteger(found) && found >= 0)
+            snapshot[name] = found;
+    }
+    return snapshot;
+};
+/** 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 const besideFleet = (own, fleet) => own.map((cell) => {
+    const match = fleet?.find((one) => one.metric === cell.metric && one.dimension === cell.dimension && one.value === cell.value);
+    if (match === undefined)
+        return cell;
+    return { ...cell, fleet: match.p95 === undefined ? { p50: match.p50 } : { p50: match.p50, p95: match.p95 } };
+});
+const fleetCellOf = (raw) => {
+    const metric = fieldOf(raw, 'metric');
+    const dimension = fieldOf(raw, 'dimension');
+    const value = fieldOf(raw, 'value');
+    const kind = fieldOf(raw, 'kind');
+    const p50 = fieldOf(raw, 'p50');
+    const p95 = fieldOf(raw, 'p95');
+    if (typeof metric !== 'string' || typeof value !== 'string' || typeof p50 !== 'number')
+        return undefined;
+    if (dimension !== 'harnessVersion' && dimension !== 'cli')
+        return undefined;
+    if (kind !== 'latency' && kind !== 'rate')
+        return undefined;
+    return { metric, dimension, value, kind, p50, ...(typeof p95 === 'number' ? { p95 } : {}) };
+};
+/** The answer as a fleet read, or undefined when it is not one; a cell that is not a cell is left out. */
+const fleetOf = (server, body) => {
+    const asOf = fieldOf(body, 'asOf');
+    const floor = fieldOf(body, 'floor');
+    const windows = fieldOf(body, 'windows');
+    if (typeof asOf !== 'string' || typeof floor !== 'number' || !Array.isArray(windows))
+        return undefined;
+    const read = [];
+    for (const window of windows) {
+        const days = fieldOf(window, 'days');
+        const cells = fieldOf(window, 'cells');
+        if (typeof days !== 'number' || !Array.isArray(cells))
+            return undefined;
+        read.push({ days, cells: cells.flatMap((cell) => fleetCellOf(cell) ?? []) });
+    }
+    return { status: 'answered', server, asOf, floor, windows: read };
+};
+/**
+ * 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 const readFleet = async (env) => {
+    if ((env.OARS_POOL_URL ?? '') === '')
+        return { status: 'not-configured' };
+    let server;
+    try {
+        const { poolServer } = await import('../sessions/pool-command.js');
+        server = poolServer(env, 'telemetry');
+    }
+    catch (error) {
+        return { status: 'unavailable', reason: error instanceof CliError ? error.message : 'the setting is not a usable server' };
+    }
+    try {
+        const reply = await fetch(`${server}/v1/telemetry/fleet`, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(FLEET_TIMEOUT_MS) });
+        if (!reply.ok)
+            return { status: 'unavailable', server, reason: `HTTP ${String(reply.status)}` };
+        const body = await reply.json().catch(() => undefined);
+        return fleetOf(server, body) ?? { status: 'unavailable', server, reason: 'the answer is not a fleet read' };
+    }
+    catch {
+        return { status: 'unavailable', server, reason: 'it could not be reached' };
+    }
+};
+const percent = (rate) => `${String(Math.round(rate * 100))}%`;
+const numbersOf = (cell) => cell.kind === 'rate' ? percent(cell.rate ?? 0) : `p50 ${String(cell.p50 ?? 0)} ms, p95 ${String(cell.p95 ?? 0)} ms`;
+const fleetNumbers = (cell, fleet) => (cell.kind === 'rate' ? `the fleet's median install: ${percent(fleet.p50)}` : `fleet p50 ${String(fleet.p50)} ms, p95 ${String(fleet.p95 ?? 0)} ms`);
+const cellLines = (cell, answered, floor) => {
+    const own = cell.kind === 'rate' ? `your rate ${percent(cell.rate ?? 0)}` : numbersOf(cell);
+    const lines = [`  ${cell.metric} (${cell.dimension === 'harnessVersion' ? 'harness/version' : cell.dimension} ${cell.value})  n=${String(cell.n)}  ${own}`];
+    if (cell.fleet !== undefined)
+        lines.push(`    ${fleetNumbers(cell, cell.fleet)}`);
+    else if (answered)
+        lines.push(`    fleet: not served (fewer than ${String(floor)} installs report this)`);
+    return lines;
+};
+const storeLine = (store) => {
+    if (store.readFailed)
+        return `Store health, as of ${store.at}: the store could not be read.`;
+    const parts = COUNTS.flatMap((name) => (store[name] === undefined ? [] : [`${name} ${String(store[name])}`]));
+    return `Store health, as of ${store.at}: ${parts.join(', ')}.`;
+};
+export const reportOf = (lines, now, fleet) => ({
+    windows: WINDOWS.map((days) => {
+        const window = fleet.status === 'answered' ? fleet.windows.find((one) => one.days === days) : undefined;
+        return { days, cells: besideFleet(ownCells(lines, now, days, fleet.status === 'answered' ? fleet.asOf : undefined), window?.cells) };
+    }),
+    store: latestStore(lines, now, Math.max(...WINDOWS)),
+    fleet,
+});
+export const textOf = (report, dir) => {
+    const { fleet } = report;
+    const answered = fleet.status === 'answered';
+    const floor = fleet.status === 'answered' ? fleet.floor : 0;
+    const out = [`Your telemetry, from the spool in ${dir}.`];
+    if (report.windows.every((window) => window.cells.length === 0) && report.store === undefined)
+        out.push('Nothing is measured in the spool yet: the hooks and nightly task record as they run.');
+    for (const window of report.windows) {
+        if (window.cells.length === 0)
+            continue;
+        out.push('', `Last ${String(window.days)} days`);
+        for (const cell of window.cells)
+            out.push(...cellLines(cell, answered, floor));
+    }
+    if (report.store !== undefined)
+        out.push('', storeLine(report.store));
+    out.push('');
+    if (fleet.status === 'not-configured')
+        out.push('No pool server is configured (OARS_POOL_URL), so these are your numbers only.');
+    else if (fleet.status === 'unavailable')
+        out.push(`The pool server${fleet.server === undefined ? '' : ` at ${fleet.server}`} did not give a fleet read (${fleet.reason}), so these are your numbers only.`);
+    else
+        out.push(`Fleet numbers are as of ${fleet.asOf}, from ${fleet.server}: percentiles over installs, served only where at least ${String(fleet.floor)} installs report. The read sent nothing of yours.`);
+    return out.join('\n');
+};

package/dist/telemetry/schema.d.ts

@@ -0,0 +1,40 @@
+import { ExitCode } from '../errors.js';
+/** Bumped when an event type or field changes meaning; every spooled event carries it. */
+export declare const SCHEMA_VERSION = 1;
+/** What an event field may hold: a closed word, a whole number, or a list of either. */
+export type Value = string | number | string[] | number[];
+/** A model or harness version as the public vocabulary knows it, else the closed word `other`: a private or gateway name never reaches the spool. */
+export declare const publicWord: (shape: (value: string | null) => string | null, value: unknown) => string;
+export declare const modelWord: (value: unknown) => string;
+export declare const versionWord: (value: unknown) => string;
+/** What went wrong, as a closed word chosen from the exit code; the error's own text never comes here. */
+export declare const ERROR_CLASSES: readonly ["usage", "auth", "invalid", "conflict", "rate-limited", "unreachable", "capped", "unexpected"];
+export type ErrorClass = (typeof ERROR_CLASSES)[number];
+/** Which hook fired: the six session hooks, and `gate` for `oars gate hook`. */
+export declare const HOOK_NAMES: readonly ["session-start", "prompt", "pre-tool", "post-tool", "stop", "nightly", "gate"];
+/** What a hook came to: it found something, found nothing, found something and held it back (the unexposed arm), or failed. */
+export declare const HOOK_OUTCOMES: readonly ["hit", "miss", "held", "error"];
+/** How a recall was asked and by whom. */
+export declare const RECALL_FORMS: readonly ["pattern", "entity", "question", "text", "legacy"];
+export declare const RECALL_MODES: readonly ["pull", "push"];
+export declare const RECALL_ARMS: readonly ["shown", "held"];
+/** The read families a recall can serve, as the program names them. */
+export declare const RECALL_FAMILY_NAMES: readonly ["recovery", "fit", "cost", "change", "live", "adoption", "method", "next-step", "tool-day", "version-boundary", "substitution", "interaction", "day-move", "entity"];
+export declare const FETCH_HARNESSES: readonly ["claude-code", "cursor", "codex", "copilot", "gemini", "grok", "opencode", "pi", "vscode-copilot", "otel", "other"];
+/** The built-in error classes a crash may name; any other class (a library's, a program's, or text set as a name) is `other`. */
+export declare const CRASH_CLASSES: readonly ["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError", "AggregateError", "other"];
+export type CrashClass = (typeof CRASH_CLASSES)[number];
+export declare const EVENT_TYPES: readonly string[];
+/** The field names a type admits, so a test can feed every one. */
+export declare const fieldNamesOf: (type: string) => string[];
+/** The error class for an exit code: closed words only. */
+export declare const errorClassOf: (exit: ExitCode) => ErrorClass | undefined;
+/** What a field set came to: the fields that fit, and how many did not (an unknown name, or a value its rule refused). */
+export interface Sanitized {
+    data: {
+        [field: string]: Value;
+    };
+    dropped: number;
+}
+/** Passes `fields` through the rules of `type`; `undefined` for a type the schema does not know. */
+export declare const sanitize: (type: string, fields: object) => Sanitized | undefined;

package/dist/telemetry/schema.js

@@ -0,0 +1,187 @@
+// The closed schema every telemetry event passes before it reaches the spool. A field the schema does not know is dropped and counted, and a value
+// that does not fit its rule is dropped the same way, so what the spool holds is bounded by this file, not by whoever wrote the event. A rule admits
+// a closed word, a small whole number, or a short list of closed words: never free text, a path, or a URL (none of them fits `TOKEN`).
+// Later briefs add event types: add one line to `EVENTS`.
+import { ExitCode } from '../errors.js';
+import { FIELD_ROWS } from '../sessions/pool-outbox.js';
+import { OTHER, HARNESSES } from '../sessions/pool-wire.js';
+import { LITERAL, publicModel, publicVersion } from '../sessions/public-vocabulary.js';
+/** Bumped when an event type or field changes meaning; every spooled event carries it. */
+export const SCHEMA_VERSION = 1;
+/** A command or option name as the program defines it: letters, digits, and hyphens. No space, slash, dot, colon, or quote. */
+const TOKEN = /^[a-z][A-Za-z0-9-]{0,31}$/;
+const tokens = (max) => (value) => Array.isArray(value) && value.length <= max && value.every((entry) => typeof entry === 'string' && TOKEN.test(entry)) ? value.map(String) : undefined;
+const whole = (max) => (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= max ? value : undefined;
+const oneOf = (allowed) => (value) => typeof value === 'string' && allowed.includes(value) ? value : undefined;
+/** A model or harness version as the public vocabulary knows it, else the closed word `other`: a private or gateway name never reaches the spool. */
+export const publicWord = (shape, value) => {
+    if (typeof value !== 'string')
+        return 'other';
+    const named = shape(value);
+    return named === null || named === LITERAL ? 'other' : named;
+};
+export const modelWord = (value) => publicWord(publicModel, value);
+export const versionWord = (value) => publicWord(publicVersion, value);
+const MODEL_OR_VERSION = (word) => (value) => typeof value === 'string' && word(value) === value ? value : undefined;
+/** A short list whose every entry is one of `allowed`. */
+const listOf = (allowed, max) => (value) => Array.isArray(value) && value.length <= max && value.every((entry) => typeof entry === 'string' && allowed.includes(entry)) ? value.map(String) : undefined;
+/** A list of whole numbers, none above `max`: the counts that sit beside a list of names. */
+const counts = (length, max) => (value) => Array.isArray(value) && value.length <= length && value.every((entry) => typeof entry === 'number' && Number.isSafeInteger(entry) && entry >= 0 && entry <= max) ? value.map(Number) : undefined;
+/** A list of names, every one of them in `allowed`. */
+const namesIn = (allowed, length) => (value) => Array.isArray(value) && value.length <= length && value.every((entry) => typeof entry === 'string' && allowed.has(entry)) ? value.map(String) : undefined;
+/** A list of values the pool wire's own public vocabulary admits, or the word `other` for one it does not: the caller maps, the schema checks again. */
+const publicList = (visible, length) => (value) => Array.isArray(value) && value.length <= length && value.every((entry) => typeof entry === 'string' && (entry === OTHER || (entry !== LITERAL && visible(entry) === entry))) ? value.map(String) : undefined;
+/** A fixed number of lowercase hexadecimal digits: a hash, which names nothing. */
+const hex = (digits) => (value) => typeof value === 'string' && new RegExp(`^[0-9a-f]{${String(digits)}}$`).test(value) ? value : undefined;
+/** A problem code as a server names it: lowercase words joined with underscores. No space, slash, dot, colon, or quote, so no path, URL, or sentence fits. */
+const CODE = /^[a-z][a-z0-9_]{0,39}$/;
+const code = (value) => (typeof value === 'string' && CODE.test(value) ? value : undefined);
+const rules = (fields) => new Map(Object.entries(fields));
+const DAY_MS = 86_400_000;
+/** What went wrong, as a closed word chosen from the exit code; the error's own text never comes here. */
+export const ERROR_CLASSES = ['usage', 'auth', 'invalid', 'conflict', 'rate-limited', 'unreachable', 'capped', 'unexpected'];
+/** Which hook fired: the six session hooks, and `gate` for `oars gate hook`. */
+export const HOOK_NAMES = ['session-start', 'prompt', 'pre-tool', 'post-tool', 'stop', 'nightly', 'gate'];
+/** What a hook came to: it found something, found nothing, found something and held it back (the unexposed arm), or failed. */
+export const HOOK_OUTCOMES = ['hit', 'miss', 'held', 'error'];
+/** How a recall was asked and by whom. */
+export const RECALL_FORMS = ['pattern', 'entity', 'question', 'text', 'legacy'];
+export const RECALL_MODES = ['pull', 'push'];
+export const RECALL_ARMS = ['shown', 'held'];
+/** The read families a recall can serve, as the program names them. */
+export const RECALL_FAMILY_NAMES = ['recovery', 'fit', 'cost', 'change', 'live', 'adoption', 'method', 'next-step', 'tool-day', 'version-boundary', 'substitution', 'interaction', 'day-move', 'entity'];
+export const FETCH_HARNESSES = ['claude-code', 'cursor', 'codex', 'copilot', 'gemini', 'grok', 'opencode', 'pi', 'vscode-copilot', 'otel', 'other'];
+const BYTES = 1 << 26;
+const COUNT = 1_000_000;
+/** The built-in error classes a crash may name; any other class (a library's, a program's, or text set as a name) is `other`. */
+export const CRASH_CLASSES = ['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'EvalError', 'URIError', 'AggregateError', 'other'];
+const HUGE = 2 ** 50;
+const ENTRIES = 1_000_000_000;
+const WIRE_NAMES = new Set(Object.keys(FIELD_ROWS));
+const WIRE_HARNESSES = [...HARNESSES, OTHER];
+/** At most as many names as the register holds, so a batch's whole field list fits. */
+const WIRE_LENGTH = WIRE_NAMES.size;
+/** One line per event type. */
+const EVENTS = new Map([
+    ['command', rules({ path: tokens(4), flags: tokens(40), durationMs: whole(DAY_MS), exitCode: whole(255), errorClass: oneOf(ERROR_CLASSES) })],
+    ['hook', rules({ name: oneOf(HOOK_NAMES), latencyMs: whole(DAY_MS), outcome: oneOf(HOOK_OUTCOMES), bytes: whole(BYTES), harness: oneOf(WIRE_HARNESSES), harnessVersion: MODEL_OR_VERSION(versionWord), model: MODEL_OR_VERSION(modelWord) })],
+    [
+        'recall',
+        rules({ form: oneOf(RECALL_FORMS), mode: oneOf(RECALL_MODES), families: listOf(RECALL_FAMILY_NAMES, 16), kind: oneOf(['hit', 'miss']), reads: whole(COUNT), evidence: whole(COUNT), tokens: whole(COUNT), arm: oneOf(RECALL_ARMS) }),
+    ],
+    [
+        'deposit',
+        rules({
+            step: oneOf(['build', 'send']),
+            sessions: whole(COUNT),
+            batched: whole(COUNT),
+            sent: whole(COUNT),
+            bytes: whole(BYTES),
+            excludedFolder: whole(COUNT),
+            excludedTerm: whole(COUNT),
+            excludedNoRaw: whole(COUNT),
+            excludedNoTerms: whole(COUNT),
+            excludedUnreadable: whole(COUNT),
+            notEnded: whole(COUNT),
+            uncaptured: whole(COUNT),
+            refused: whole(COUNT),
+            withdrawn: whole(COUNT),
+            discarded: whole(COUNT),
+        }),
+    ],
+    ['fetch', rules({ harness: oneOf(FETCH_HARNESSES), fetches: whole(COUNT), etagHits: whole(COUNT), capHits: whole(COUNT), reads: whole(COUNT) })],
+    // The nightly snapshot of the session store. `readFailed` is 1 when the store could not be read, and then no count is sent.
+    [
+        'store-health',
+        rules({
+            readFailed: whole(1),
+            sessions: whole(ENTRIES),
+            subagents: whole(ENTRIES),
+            skeletons: whole(ENTRIES),
+            unparseable: whole(ENTRIES),
+            rawBytes: whole(HUGE),
+            verifyChecked: whole(ENTRIES),
+            verifyFailed: whole(ENTRIES),
+            captureVersions: counts(32, 10_000),
+            extractorVersions: counts(32, 10_000),
+            harnessVersions: publicList(publicVersion, 32),
+            models: publicList(publicModel, 32),
+            outboxBytes: whole(HUGE),
+            egressBytes: whole(HUGE),
+        }),
+    ],
+    // What one nightly run cost. `failed` is 1 when the run failed.
+    ['run-cost', rules({ totalMs: whole(DAY_MS), parseMs: whole(DAY_MS), peakRssMb: whole(1_000_000), failed: whole(1) })],
+    // An error nobody planned for: its class and a hash of its stack. Never its message.
+    ['crash', rules({ errorClass: oneOf(CRASH_CLASSES), stackHash: hex(16) })],
+    // One deposit pass, for one harness: the register's field names, and beside them how many batches held each and how many bytes it took.
+    [
+        'wire',
+        rules({
+            harness: oneOf(WIRE_HARNESSES),
+            batches: whole(ENTRIES),
+            bytes: whole(HUGE),
+            fields: namesIn(WIRE_NAMES, WIRE_LENGTH),
+            present: counts(WIRE_LENGTH, ENTRIES),
+            fieldBytes: counts(WIRE_LENGTH, HUGE),
+        }),
+    ],
+    // One send of one batch: whether the pool took it, the HTTP status, and the code of its refusal.
+    ['wire-send', rules({ sent: whole(1), status: whole(599), code, bytes: whole(HUGE) })],
+]);
+export const EVENT_TYPES = [...EVENTS.keys()];
+/** The field names a type admits, so a test can feed every one. */
+export const fieldNamesOf = (type) => [...(EVENTS.get(type)?.keys() ?? [])];
+/** The error class for an exit code: closed words only. */
+export const errorClassOf = (exit) => {
+    switch (exit) {
+        case ExitCode.OK:
+            return undefined;
+        case ExitCode.USAGE:
+            return 'usage';
+        case ExitCode.AUTH:
+            return 'auth';
+        case ExitCode.INVALID:
+            return 'invalid';
+        case ExitCode.CONFLICT:
+            return 'conflict';
+        case ExitCode.RATE_LIMITED:
+            return 'rate-limited';
+        case ExitCode.UNREACHABLE:
+            return 'unreachable';
+        case ExitCode.CAPPED:
+            return 'capped';
+        default:
+            return 'unexpected';
+    }
+};
+/** The lists of a `wire` event that are read index by index, so one refused (or a different length) would leave the others misaligned. */
+const PARALLEL_LISTS = ['fields', 'present', 'fieldBytes'];
+/** Keeps the parallel lists only when every one sent came through and they are the same length; otherwise none of them, each kept one counted as dropped. */
+const alignParallel = (sent, data, dropped) => {
+    const given = PARALLEL_LISTS.filter((name) => name in sent);
+    const kept = given.filter((name) => data[name] !== undefined);
+    // Every rule for these three names returns a list, so `flat` of the one-element wrapper is that list's length.
+    const lengths = new Set(kept.map((name) => [data[name]].flat().length));
+    if (kept.length === given.length && lengths.size <= 1)
+        return { data, dropped };
+    for (const name of kept)
+        Reflect.deleteProperty(data, name);
+    return { data, dropped: dropped + kept.length };
+};
+/** Passes `fields` through the rules of `type`; `undefined` for a type the schema does not know. */
+export const sanitize = (type, fields) => {
+    const known = EVENTS.get(type);
+    if (known === undefined)
+        return undefined;
+    const data = {};
+    let dropped = 0;
+    for (const [name, value] of Object.entries(fields)) {
+        const accepted = known.get(name)?.(value);
+        if (accepted === undefined)
+            dropped += 1;
+        else
+            data[name] = accepted;
+    }
+    return type === 'wire' ? alignParallel(fields, data, dropped) : { data, dropped };
+};

package/dist/telemetry/send-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telemetry/send-main.js

@@ -0,0 +1,11 @@
+// The entry `startDailySend` starts, detached: `node send-main.js <telemetry folder>`. It prints nothing, answers nothing, and exits 0 whatever happens; nobody waits on it.
+import { sendSpool } from './send.js';
+const [dir] = process.argv.slice(2);
+try {
+    if (dir !== undefined)
+        await sendSpool({ env: process.env, dir, now: Date.now });
+}
+catch {
+    // Fail-open: the spool is sent at the next try.
+}
+process.exit(0);

package/dist/telemetry/send.d.ts

@@ -0,0 +1,36 @@
+import type { HelperSpawn } from '../gate/hook-fill.js';
+import type { TelemetryRuntime } from './record.js';
+/** The pool route takes at most this many events (Analytics Engine's per-request write limit). */
+export declare const BATCH_EVENTS = 250;
+/** One request's whole life, connect to last byte; a server that is slower than this is treated as down. */
+export declare const SEND_TIMEOUT_MS = 10000;
+export interface SendDeps {
+    env: NodeJS.ProcessEnv;
+    /** `<config>/oars/telemetry`. */
+    dir: string;
+    now: () => number;
+    /** The network, for a test; absent means the global `fetch`. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface SendResult {
+    outcome: 'sent' | 'failed' | 'empty' | 'not-allowed' | 'no-server';
+    /** Events the server took (and that were cleared from the spool). */
+    sent: number;
+    /** Requests made, including one that failed. */
+    requests: number;
+}
+export declare const writeMark: (dir: string, now: number) => void;
+/** Whether a day has passed since the last send was started. A missing, unreadable, or future mark counts as due. */
+export declare const dueForSend: (dir: string, now: number) => boolean;
+/** Sends what the spool holds. Never throws. */
+export declare const sendSpool: (deps: SendDeps) => Promise<SendResult>;
+/** The nightly task's send, in the telemetry folder under the config folder. */
+export declare const sendNightly: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string, now: () => number) => Promise<SendResult>;
+/**
+ * Called after an interactive command: starts one detached send, at most once a day, when sending is allowed. The mark is written first, so two commands at
+ * once start one. Nothing here throws or waits, and the run has no way to start a send unless `main.ts` gave it one.
+ */
+export declare const startDailySend: (runtime: TelemetryRuntime, env: NodeJS.ProcessEnv, now: number) => void;
+/** Starts `send-main.js` detached with no stdio and never waits for it, as the gate's helper is started. */
+export declare const spawnDetachedSend: (dir: string, start?: HelperSpawn) => void;