@trazum/cli 1.42.0 → 1.44.0

package/src/i18n/types.ts

@@ -1,4 +1,4 @@
-import type { CannotTellReason, EvalVerdict, Locale, PlanActionKind, PlanAssumption, RuleLevel, VerifyOutcome } from '@trazum/core';
+import type { CannotTellReason, EvalVerdict, Locale, NotJudgeable, PlanActionKind, PlanAssumption, RuleLevel, VerifyOutcome, WatchGate } from '@trazum/core';
 
 /**
  * The CLI's own message catalogue.
@@ -1072,6 +1072,49 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum serve` — the answer given before the call is sent.
+   *
+   * The copy states the two things a reader must not have to infer: that this
+   * listens on loopback and nowhere else, and that the measured half is read
+   * once rather than being current to the second.
+   */
+  serve: {
+    listening(where: string): string;
+    /** Why there is no --host, and why that is not an omission. */
+    loopbackOnly(): string;
+    measuredFrom(usd: string): string;
+    nothingMeasured(dir: string): string;
+    noBudget(): string;
+    badPort(value: string): string;
+  };
+
+  /**
+   * `trazum watch` — the gates, evaluated as the money moves.
+   *
+   * The copy here carries the rule that makes an alert at 3am trustworthy: a
+   * crossing is measured, never projected, and a period too short to judge is
+   * said to be rather than passed.
+   */
+  watch: {
+    /** Watching with no threshold configured is a green light nobody earned. */
+    noThresholds(): string;
+    nothingToWatch(dir: string): string;
+    intervalTooTight(): string;
+    badWebhook(reason: 'invalid-url' | 'credentials-in-url' | 'insecure-scheme'): string;
+    /** A measured crossing. `day` names the afternoon when the gate is a day gate. */
+    crossed(gate: WatchGate, measured: string, limit: string, day: string | null): string;
+    /** Still over the limit, and already reported — quiet, but not clean. */
+    stillOver(gate: WatchGate, measured: string, limit: string, day: string | null): string;
+    /** Neither a pass nor a failure: this cannot be judged yet, and why. */
+    notJudgeable(gate: WatchGate, reason: NotJudgeable, covered: string | null): string;
+    /** The stretch nobody was watching, named rather than implied away. */
+    gap(from: string, to: string): string;
+    allWithin(gates: string): string;
+    webhookFailed(status: string): string;
+    watching(minutes: string): string;
+  };
+
   /**
    * `trazum store` — the measurements kept on disk.
    *

package/src/index.ts

@@ -20,6 +20,8 @@ import {
   normalizeAnthropicUsage,
   normalizeOpenAIUsage,
   bucketsFromRecords,
+  evaluateWatch,
+  firedKey,
   pruneRecords,
   recordsFromBuckets,
   storeInventory,
@@ -146,6 +148,14 @@ import {
 import type { Revision } from './git.js';
 import { fetchProviderUsage } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import { DEFAULT_PORT, buildServer, listen } from './serve.js';
+import {
+  WATCH_STATE_VERSION,
+  checkWebhook,
+  postWebhook,
+  readWatchState,
+  writeWatchState,
+} from './watch-run.js';
 import { detectLocale, getCliMessages } from './i18n/index.js';
 import {
   MAX_SUMMARY_CHARS,
@@ -196,6 +206,10 @@ const VALUE_FLAGS = new Set([
   'min-usd',
   'payload',
   'keep',
+  'interval',
+  'webhook',
+  'port',
+  'socket',
   // `route` takes a path here, and the flag is deliberately not `--prompt`:
   // everywhere else in this tool `--prompt` names a marked prompt *inside* a
   // source file, and reusing it for a path would be a trap laid for the reader.
@@ -501,6 +515,8 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   history: ['store', 'json', 'markdown-out'],
   connect: ['since', 'until', 'payload', 'store', 'json', 'out', 'markdown-out', 'pricing', 'pricing-live', 'dry-run'],
   store: ['prune', 'keep', 'json', 'pricing', 'pricing-live', 'dry-run'],
+  watch: ['once', 'interval', 'since', 'payload', 'webhook', 'json', 'pricing', 'pricing-live'],
+  serve: ['port', 'socket', 'pricing', 'pricing-live'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2282,6 +2298,285 @@ function parseWhen(
   throw new Error(t.profile.badWhen(flag, value));
 }
 
+/**
+ * `trazum serve` — the answer in milliseconds.
+ *
+ * The measured position is read once at start rather than per request: the
+ * whole promise is a single-digit-millisecond answer, and a file read in the
+ * hot path cannot make it. That staleness is real, so every answer carries the
+ * window its measurement covers instead of implying it is current to the
+ * second.
+ */
+async function commandServe(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const root = process.cwd();
+  const limitUsd = config.spend?.maxUsd;
+
+  const { resolved } = await readStore(root);
+  const measured = resolved.records.length > 0;
+  /**
+   * The window the measurement covers, carried into every answer.
+   *
+   * The position is read once at start, so a caller has to be able to see how
+   * old it is. A null window here would let a figure from last month read as
+   * current, which is the staleness this endpoint is otherwise honest about.
+   */
+  const window = measured
+    ? {
+        fromMs: Math.min(...resolved.records.map((record) => record.fromMs)),
+        toMs: Math.max(...resolved.records.map((record) => record.toMs)),
+      }
+    : null;
+  const report = bucketedProfile(
+    {
+      provider: 'store',
+      granularity: 'bucketed',
+      buckets: bucketsFromRecords(resolved.records),
+      window,
+      gaps: [],
+      unavailable: [],
+    },
+    { catalogue: pricing },
+  );
+
+  const server = buildServer({
+    catalogue: pricing,
+    position: () => ({
+      consumedUsd: measured ? report.total.totalUsd : undefined,
+      limitUsd,
+      window: report.span,
+    }),
+  });
+
+  const socket = stringFlag(args, 'socket');
+  const portRaw = stringFlag(args, 'port');
+  const port = portRaw === undefined ? DEFAULT_PORT : Number(portRaw);
+  if (socket === undefined && (!Number.isInteger(port) || port < 0 || port > 65_535)) {
+    throw new Error(t.serve.badPort(String(portRaw)));
+  }
+
+  const where = await listen(server, socket !== undefined ? { socket } : { port });
+  console.log(c.bold(t.serve.listening(where)));
+  console.log(`  ${c.dim(wrap(t.serve.loopbackOnly(), 74, '    '))}`);
+  console.log(
+    `  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(report.total.totalUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`,
+  );
+  if (limitUsd === undefined) {
+    console.log(`  ${c.dim(wrap(t.serve.noBudget(), 74, '    '))}`);
+  }
+}
+
+/**
+ * `trazum watch` — the afternoon it happened, said that afternoon.
+ *
+ * One cycle is the primitive: measure, keep, evaluate, emit, remember. The
+ * loop is that cycle in a timer, so a cron entry and a foreground watcher run
+ * exactly the same code and the tests exercise the thing that ships.
+ *
+ * Three transports, all boring on purpose: a non-zero exit code so cron mails
+ * it, a JSON event on stdout so any pipeline can read it, and a webhook for
+ * the operator who already has somewhere for alerts to go. No hosted service
+ * and no account.
+ */
+async function commandWatch(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const root = process.cwd();
+  const asJson = boolFlag(args, 'json');
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const day = (msValue: number): string => new Date(msValue).toISOString().slice(0, 10);
+
+  const thresholds = {
+    maxUsd: config.spend?.maxUsd,
+    maxDayUsd: config.spend?.maxDayUsd,
+    maxCacheLossUsd: config.spend?.maxCacheLossUsd,
+  };
+  if (
+    thresholds.maxUsd === undefined &&
+    thresholds.maxDayUsd === undefined &&
+    thresholds.maxCacheLossUsd === undefined
+  ) {
+    throw new Error(t.watch.noThresholds());
+  }
+
+  /**
+   * A webhook is a new outbound surface, so it is checked before anything is
+   * sent: credentials in a URL end up in logs and shell history, and an alert
+   * carrying spend figures over plain http across a network is a leak the
+   * operator did not ask for. Loopback is the exception, because pointing a
+   * watcher at your own alerting daemon is the ordinary case.
+   */
+  const webhookRaw = stringFlag(args, 'webhook');
+  let webhook: URL | null = null;
+  if (webhookRaw !== undefined) {
+    const checked = checkWebhook(webhookRaw);
+    if (!checked.ok) throw new Error(t.watch.badWebhook(checked.reason));
+    webhook = checked.url;
+  }
+
+  const intervalRaw = stringFlag(args, 'interval');
+  const once = boolFlag(args, 'once') || intervalRaw === undefined;
+  let intervalMs = 0;
+  if (!once) {
+    const match = /^(\d+)(m|h)$/.exec(intervalRaw!);
+    const amount = match === null ? NaN : Number(match[1]);
+    intervalMs = match?.[2] === 'h' ? amount * 3_600_000 : amount * 60_000;
+    // Usage APIs are rate limited, and a tight loop is a way to get somebody's
+    // key throttled by a tool that was supposed to save them money.
+    if (!Number.isFinite(intervalMs) || intervalMs < 5 * 60_000) {
+      throw new Error(t.watch.intervalTooTight());
+    }
+  }
+
+  const cycle = async (): Promise<number> => {
+    const state = await readWatchState(root);
+    const nowMs = Date.now();
+
+    /**
+     * Where the measurements come from: a saved payload when one is named
+     * (which is how this is tested and how an air-gapped run works), and the
+     * store otherwise. A cycle that found nothing to measure says so — a
+     * watcher over nothing is a green light nobody earned.
+     */
+    const payloadPath = stringFlag(args, 'payload');
+    let pull;
+    if (payloadPath !== undefined) {
+      pull = normalizeAnthropicUsage(JSON.parse(await readFile(payloadPath, 'utf8')));
+    } else {
+      const { resolved } = await readStore(root);
+      if (resolved.records.length === 0) throw new Error(t.watch.nothingToWatch(STORE_DIR));
+      pull = {
+        provider: 'store',
+        granularity: 'bucketed' as const,
+        buckets: bucketsFromRecords(resolved.records),
+        window: null,
+        gaps: [],
+        unavailable: [],
+      };
+    }
+
+    const report = bucketedProfile(pull, { catalogue: pricing });
+    const cache = bucketedCacheEconomics(report);
+    const result = evaluateWatch({
+      report,
+      thresholds,
+      cacheDeltaUsd: cache.verdict === 'no-cache' ? undefined : cache.deltaUsd,
+      nowMs,
+      lastCoveredToMs: state?.lastCoveredToMs ?? undefined,
+      alreadyFired: new Set(Object.keys(state?.fired ?? {})),
+    });
+
+    if (asJson) {
+      console.log(JSON.stringify({ schemaVersion: 1, firedAtMs: nowMs, ...result }, null, 2));
+    } else {
+      if (result.gap !== null) {
+        console.log(c.yellow(wrap(t.watch.gap(day(result.gap.fromMs), day(result.gap.toMs)), 76, '  ')));
+      }
+      for (const crossing of result.crossings) {
+        console.log(
+          c.red(
+            wrap(
+              t.watch.crossed(
+                crossing.gate,
+                formatUsd(crossing.measuredUsd),
+                formatUsd(crossing.limitUsd),
+                crossing.day,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      for (const abstention of result.abstentions) {
+        console.log(
+          c.dim(
+            wrap(
+              t.watch.notJudgeable(
+                abstention.gate,
+                abstention.reason,
+                abstention.detail === null
+                  ? null
+                  : `${Math.round((abstention.detail.coveredMs / abstention.detail.neededMs) * 100)}%`,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      for (const still of result.suppressed) {
+        console.log(
+          c.yellow(
+            wrap(
+              t.watch.stillOver(
+                still.gate,
+                formatUsd(still.measuredUsd),
+                formatUsd(still.limitUsd),
+                still.day,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      if (
+        result.crossings.length === 0 &&
+        result.suppressed.length === 0 &&
+        result.abstentions.length === 0
+      ) {
+        console.log(c.green(wrap(t.watch.allWithin(n(Object.keys(thresholds).filter((k) => thresholds[k as keyof typeof thresholds] !== undefined).length)), 76, '  ')));
+      }
+    }
+
+    if (webhook !== null && result.crossings.length > 0) {
+      const sent = await postWebhook(webhook, {
+        schemaVersion: 1,
+        firedAtMs: nowMs,
+        crossings: result.crossings,
+      });
+      if (!sent.ok) {
+        // Reported and swallowed: the exit code and the event already carried
+        // the crossing, and losing those because a receiver is down would make
+        // the quietest failure the loudest one.
+        console.error(c.yellow(t.watch.webhookFailed(sent.status === null ? sent.error ?? '' : String(sent.status))));
+      }
+    }
+
+    const fired = { ...(state?.fired ?? {}) };
+    for (const crossing of result.crossings) fired[firedKey(crossing.gate, crossing.day)] = nowMs;
+    await writeWatchState(root, {
+      v: WATCH_STATE_VERSION,
+      lastCycleMs: nowMs,
+      lastCoveredToMs: report.span?.toMs ?? state?.lastCoveredToMs ?? null,
+      fired,
+    });
+
+    return result.crossings.length + result.suppressed.length;
+  };
+
+  const crossed = await cycle();
+  // Still over is still a failure: only the alert was already sent.
+  if (crossed > 0) process.exitCode = 1;
+  if (once) return;
+
+  console.log(c.dim(t.watch.watching(String(Math.round(intervalMs / 60_000)))));
+  // The loop is the cycle in a timer and nothing more, so the primitive above
+  // is the only thing that ever needs testing.
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    await cycle();
+  }
+}
+
 /**
  * `trazum store` — what is kept, and what a prune would take.
  *
@@ -6866,6 +7161,12 @@ async function main(): Promise<void> {
     case 'store':
       await commandStore(args, config, pricing, t);
       break;
+    case 'watch':
+      await commandWatch(args, config, pricing, t);
+      break;
+    case 'serve':
+      await commandServe(args, config, pricing, t);
+      break;
     case 'route':
       await commandRoute(args, pricing, t);
       break;

package/src/serve.ts

@@ -0,0 +1,149 @@
+/**
+ * The endpoint that answers before the call is sent.
+ *
+ * **Loopback only, and the address is not a flag.** A cost oracle listening on
+ * a network interface is an attack surface with a very small upside: it holds
+ * a company's spend, its model mix and its budgets, and it answers anybody who
+ * asks. `checkedEndpoint` has guarded Trazum's *outbound* requests since 1.14
+ * on the principle that a caller selects an endpoint rather than naming one;
+ * this is the inbound counterpart, and it is enforced the same way — by there
+ * being no way to say otherwise. `127.0.0.1` is compiled in. A Unix socket is
+ * offered for callers that would rather not use a port at all.
+ *
+ * **No auth, on purpose.** Anything reachable only from the machine it runs on
+ * is already behind the operating system's own boundary, and a token checked
+ * over loopback is theatre: whoever can reach the socket can read the token
+ * out of the process that holds it. The honest posture is a surface small
+ * enough not to need one.
+ *
+ * **It degrades rather than failing.** With no store and no budget the
+ * endpoint still prices the call from the bundled catalogue and says the
+ * budget half is unknown. Offline is a mode, not an error, and an oracle that
+ * refuses to speak when half its inputs are missing is an oracle nobody wires
+ * into a hot path.
+ */
+
+import { createServer } from 'node:http';
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { answerCost } from '@trazum/core';
+import type { CostAnswer, PricingCatalogue } from '@trazum/core';
+
+/** Compiled in. See the module note: this is the inbound SSRF posture. */
+export const BIND_HOST = '127.0.0.1';
+
+export const DEFAULT_PORT = 7317;
+
+/**
+ * Bodies larger than this are refused unread.
+ *
+ * A prompt is text and text is unbounded; a hot-path oracle that will buffer
+ * whatever it is handed is a memory exhaustion away from taking the caller
+ * down with it — and the caller was asking how to spend *less*.
+ */
+export const MAX_BODY_BYTES = 1_000_000;
+
+export interface ServeContext {
+  catalogue: PricingCatalogue;
+  /**
+   * Measured spend and the budget it is judged against, read once at start
+   * and refreshed by the caller.
+   *
+   * Read once because the whole promise here is single-digit milliseconds,
+   * and a file read in the request path cannot make that promise. The staleness
+   * is a real cost, so the answer carries the window its measurement covers
+   * rather than implying it is current to the second.
+   */
+  position: () => { consumedUsd?: number; limitUsd?: number; window?: { fromMs: number; toMs: number } | null };
+}
+
+async function readBody(request: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) throw new Error('body too large');
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+const send = (response: ServerResponse, status: number, body: unknown): void => {
+  const text = JSON.stringify(body);
+  response.writeHead(status, {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(text),
+    // Nothing here is for a browser to read across origins, and saying so
+    // costs one header.
+    'cache-control': 'no-store',
+  });
+  response.end(text);
+};
+
+export function buildServer(context: ServeContext): Server {
+  return createServer((request, response) => {
+    void (async () => {
+      const url = new URL(request.url ?? '/', `http://${BIND_HOST}`);
+
+      if (request.method === 'GET' && url.pathname === '/health') {
+        send(response, 200, { ok: true, schemaVersion: 1 });
+        return;
+      }
+
+      if (request.method !== 'POST' || url.pathname !== '/cost') {
+        send(response, 404, {
+          error: 'not-found',
+          detail: 'POST /cost, or GET /health.',
+        });
+        return;
+      }
+
+      let payload: Record<string, unknown>;
+      try {
+        const raw = await readBody(request);
+        payload = raw.trim() === '' ? {} : (JSON.parse(raw) as Record<string, unknown>);
+      } catch (error) {
+        send(response, 400, {
+          error: 'bad-request',
+          detail: error instanceof Error && error.message === 'body too large'
+            ? `A request body may be at most ${MAX_BODY_BYTES} bytes.`
+            : 'The body must be JSON.',
+        });
+        return;
+      }
+
+      const position = context.position();
+      const answer: CostAnswer = answerCost(
+        {
+          model: typeof payload.model === 'string' ? payload.model : undefined,
+          inputTokens: typeof payload.inputTokens === 'number' ? payload.inputTokens : undefined,
+          outputTokens: typeof payload.outputTokens === 'number' ? payload.outputTokens : undefined,
+          basis: payload.basis === 'heuristic' ? 'heuristic' : 'token-count',
+          ...position,
+        },
+        { catalogue: context.catalogue },
+      );
+      send(response, 200, answer);
+    })();
+  });
+}
+
+export interface ListenTarget {
+  /** A Unix socket path, when the caller would rather not use a port. */
+  socket?: string;
+  port?: number;
+}
+
+export function listen(server: Server, target: ListenTarget): Promise<string> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    if (target.socket !== undefined) {
+      server.listen(target.socket, () => resolve(target.socket!));
+      return;
+    }
+    // The host is not a parameter. See the module note.
+    server.listen(target.port ?? DEFAULT_PORT, BIND_HOST, () => {
+      const address = server.address();
+      resolve(typeof address === 'object' && address !== null ? `${BIND_HOST}:${address.port}` : String(address));
+    });
+  });
+}

package/src/watch-run.ts

@@ -0,0 +1,126 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+import type { WatchCrossing } from '@trazum/core';
+
+export const WATCH_STATE_FILE = '.trazum/watch.json';
+
+export const WATCH_STATE_VERSION = 1;
+
+export interface WatchState {
+  v: number;
+  /** When the last cycle ran, so a long silence can be told from a first run. */
+  lastCycleMs: number;
+  /** How far the measurements reached, for the coverage gap. */
+  lastCoveredToMs: number | null;
+  /** Gate keys already alerted on, so a restart is not amnesia. */
+  fired: Record<string, number>;
+}
+
+export async function readWatchState(root: string): Promise<WatchState | null> {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, WATCH_STATE_FILE), 'utf8')) as WatchState;
+    if (parsed?.v !== WATCH_STATE_VERSION) return null;
+    return parsed;
+  } catch {
+    // No state, or state this version cannot read: a first cycle either way,
+    // which is a state the caller reports rather than an error.
+    return null;
+  }
+}
+
+export async function writeWatchState(root: string, state: WatchState): Promise<void> {
+  const path = join(root, WATCH_STATE_FILE);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+
+/**
+ * Whether a webhook URL is one this tool will post to.
+ *
+ * **This is not the SSRF case and the difference matters.** `checkedEndpoint`
+ * exists because a *request body* must never name a host: an anonymous caller
+ * pointing a shared server at an internal address is somebody else's machine
+ * reaching somewhere it was never meant to. Here the URL is in the operator's
+ * own config, on their own machine, and pointing it at their own alerting
+ * daemon on loopback is the ordinary case rather than the attack.
+ *
+ * So loopback is allowed and plain http is allowed *only* there, while two
+ * rules stay absolute: no credentials embedded in the URL, because a URL ends
+ * up in logs and shell history; and https everywhere else, because an alert
+ * carries spend figures across a network.
+ */
+export type WebhookRejection = 'invalid-url' | 'credentials-in-url' | 'insecure-scheme';
+
+export function checkWebhook(raw: string): { ok: true; url: URL } | { ok: false; reason: WebhookRejection } {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, reason: 'invalid-url' };
+  }
+  if (url.username !== '' || url.password !== '') {
+    return { ok: false, reason: 'credentials-in-url' };
+  }
+  const loopback =
+    url.hostname === 'localhost' ||
+    url.hostname === '127.0.0.1' ||
+    url.hostname === '[::1]' ||
+    url.hostname === '::1';
+  if (url.protocol === 'https:') return { ok: true, url };
+  if (url.protocol === 'http:' && loopback) return { ok: true, url };
+  return { ok: false, reason: 'insecure-scheme' };
+}
+
+/**
+ * The alert payload.
+ *
+ * Figures and gate names, never prompt text — the store has never held any and
+ * neither does this. Every crossing carries its own provenance, so a receiver
+ * that fans these into a dashboard cannot lose track of what kind of number it
+ * is holding.
+ */
+export interface WatchAlert {
+  schemaVersion: 1;
+  firedAtMs: number;
+  crossings: WatchCrossing[];
+}
+
+export async function postWebhook(
+  url: URL,
+  alert: WatchAlert,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; status: number | null; error: string | null }> {
+  try {
+    const response = await fetchImpl(url.toString(), {
+      ...SAFE_FETCH_INIT,
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(alert),
+      signal: AbortSignal.timeout(10_000),
+    });
+    return { ok: response.ok, status: response.status, error: null };
+  } catch (error) {
+    /**
+     * A webhook that will not deliver must not take the alert down with it.
+     * The exit code and the stdout event have already carried the crossing;
+     * losing those because a receiver is down would make the quietest failure
+     * the loudest one.
+     */
+    return { ok: false, status: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}