cursedbelt-server 1.0.2 → 1.1.0

package/dist/server/index.d.ts

@@ -10,6 +10,7 @@ export { type CreateJobRunnerOptions, createFireQueue, createJobRunner, createPo
 export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, extractThumbnail, ffmpegTimeToSeconds, isFfmpegAvailable, isFfprobeAvailable, type ProbeResult, parseFfmpegProgress, parseFfprobe, probeMedia, renderImage, trimVideo, type VideoCodecPlan, videoCodecPlan, } from './media-bun';
 export { createMetricsBuffer, type MetricRow, type MetricsBuffer, type MetricsBufferOptions, } from './metrics/metricsBuffer';
 export { normalizeRoute } from './metrics/normalizeRoute';
+export { type AnalyticsEngineDataset, createTelemetrySink, TELEMETRY_POINT_VERSION, type TelemetryEvent, type TelemetrySink, type TelemetrySinkOptions, toDataPoint, } from './metrics/telemetrySink';
 export { correlationId } from './middleware/correlationId';
 export { type CorsOpts, corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';
 export { errorEnvelope } from './middleware/errorEnvelope';

package/dist/server/index.js

@@ -27,6 +27,7 @@ export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, extractThumbnail, ff
 // ── Metrics ───────────────────────────────────────────────────────────────────
 export { createMetricsBuffer, } from './metrics/metricsBuffer';
 export { normalizeRoute } from './metrics/normalizeRoute';
+export { createTelemetrySink, TELEMETRY_POINT_VERSION, toDataPoint, } from './metrics/telemetrySink';
 // ── Middleware ────────────────────────────────────────────────────────────────
 export { correlationId } from './middleware/correlationId';
 export { corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';

package/dist/server/metrics/telemetrySink.d.ts

@@ -0,0 +1,119 @@
+import type { Database } from 'bun:sqlite';
+import { type MetricRow } from './metricsBuffer';
+/**
+ * ONE seam for "this app served a request", with two backends and no third.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * `request_metrics` is a row per request. On D1 that is the one line in
+ * Cloudflare's pricing with a dollar-scale overage — **$1.00 per million rows
+ * written** — and a row per request is precisely the shape that buys it. Workers
+ * Analytics Engine is purpose-built for the same job: `writeDataPoint()` per
+ * event, SQL to query, unlimited cardinality, **10M data points and 1M read
+ * queries included per month**, and **zero** database writes.
+ *
+ * 🔴 **Adopt it for the ALLOWANCE, not because it is unbilled today.**
+ * Cloudflare's own wording is that you "will not be billed for your use of
+ * Workers Analytics Engine" today and that the published prices are "shared in
+ * advance… once Cloudflare starts billing for usage in the coming months". The
+ * free-today part is temporary; the allowance is not. At this fleet's measured
+ * ~1M requests/month the bill is $0 either way, so building against the
+ * allowance makes the billing switch a non-event.
+ *
+ * ── Why not `prom-client` / a `/metrics` scrape ──────────────────────────────
+ * A scrape genuinely does turn many writes into one, and on a long-lived Bun
+ * process it would work. A Worker is **a stateless V8 isolate with no
+ * long-lived process**: isolates are created and destroyed between requests and
+ * run concurrently in many datacentres, so a `/metrics` scrape reaches ONE
+ * arbitrary isolate holding a random fraction of the counters. The in-process
+ * registry has nowhere to live. (A Durable Object does have a durable identity
+ * *and* memory, and is the real `prom-client` analogue — but it is a whole
+ * stateful object to operate for counters Analytics Engine already aggregates.
+ * Prometheus itself also needs an always-on host to scrape FROM, and that host
+ * is the Mac this fleet is trying to switch off.)
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ * · `analytics` bound  → one `writeDataPoint` per event, **zero** SQLite/D1 rows.
+ * · no `analytics`     → the existing {@link MetricsBuffer}, byte-for-byte
+ *                        unchanged, so the gate and a Mac-hosted app keep working.
+ * Both are proven by `telemetrySink.spec.ts`, which is the point of the seam:
+ * the choice is made ONCE here rather than per app.
+ */
+/**
+ * The Workers Analytics Engine binding, typed locally so this package needs no
+ * dependency on `@cloudflare/workers-types` (it is a Bun/Hono package, and a
+ * Worker supplies the real binding at runtime).
+ *
+ * Platform limits, which {@link toDataPoint} respects:
+ * **1** index of ≤96 bytes, ≤**20** blobs totalling ≤5120 bytes, ≤**20** doubles.
+ */
+export interface AnalyticsEngineDataset {
+    writeDataPoint(point: {
+        indexes?: (ArrayBuffer | string | null)[];
+        blobs?: (ArrayBuffer | string | null)[];
+        doubles?: number[];
+    }): void;
+}
+/** One request's telemetry. Identical to {@link MetricRow} — the seam does not re-shape it. */
+export type TelemetryEvent = MetricRow;
+/**
+ * A superset-compatible shape: a {@link MetricsBuffer} IS a `TelemetrySink`, so
+ * an app that already owns a buffer can keep passing it.
+ */
+export interface TelemetrySink {
+    /** Enqueue one request's telemetry. Never blocks the response. */
+    record(event: TelemetryEvent): void;
+    /** Force whatever is pending out now (shutdown + tests). No-op on Analytics Engine. */
+    flush(): void;
+    /** Stop any timer and drain. No-op on Analytics Engine. */
+    stop(): void;
+    /** Events pending locally. Always 0 on Analytics Engine — it has no buffer to hold. */
+    readonly size: number;
+}
+export interface TelemetrySinkOptions {
+    /**
+     * The Analytics Engine binding, when the platform supplies one. Present ⇒ it
+     * WINS, and `db` is never written. `null`/`undefined` ⇒ the SQLite path.
+     */
+    analytics?: AnalyticsEngineDataset | null;
+    /** The `request_metrics` database. Required unless `analytics` is bound. */
+    db?: Database | null;
+    /** Flush cadence for the SQLite path, in ms. Default: 1500. Ignored by Analytics Engine. */
+    flushIntervalMs?: number;
+    /** Eager-flush threshold for the SQLite path. Default: 5000. Ignored by Analytics Engine. */
+    maxSize?: number;
+}
+/**
+ * 🔴 **The data-point layout is a WIRE FORMAT.** Analytics Engine columns are
+ * positional (`blob1`, `double1`, …), so every saved SQL query breaks if a
+ * position moves. Append only; never reorder, never repurpose.
+ *
+ * ```
+ * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
+ * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
+ * double1 = status          double2 = durationMs             double3 = bytesOut
+ * ```
+ *
+ * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
+ * column, so sending ours would store the same instant twice.
+ *
+ * `-1` is the "unknown" marker for all three doubles, because a positional
+ * doubles array cannot hold a null and `0` is a real value for every one of them
+ * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
+ */
+export declare const TELEMETRY_POINT_VERSION = 1;
+/** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
+export declare function toDataPoint(event: TelemetryEvent): {
+    indexes: string[];
+    blobs: string[];
+    doubles: number[];
+};
+/**
+ * Build the sink for whatever platform this process is on.
+ *
+ * Throws when NEITHER backend is available, on purpose. "An app with no
+ * `request_metrics` is not quiet; it is unmeasured" — and a sink that silently
+ * drops every event is exactly the failure this seam exists to end. A misbound
+ * Worker should fail at construction, in the deploy, rather than serve traffic
+ * that nothing can see.
+ */
+export declare function createTelemetrySink(opts: TelemetrySinkOptions): TelemetrySink;

package/dist/server/metrics/telemetrySink.js

@@ -0,0 +1,76 @@
+import { createMetricsBuffer } from './metricsBuffer';
+/**
+ * 🔴 **The data-point layout is a WIRE FORMAT.** Analytics Engine columns are
+ * positional (`blob1`, `double1`, …), so every saved SQL query breaks if a
+ * position moves. Append only; never reorder, never repurpose.
+ *
+ * ```
+ * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
+ * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
+ * double1 = status          double2 = durationMs             double3 = bytesOut
+ * ```
+ *
+ * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
+ * column, so sending ours would store the same instant twice.
+ *
+ * `-1` is the "unknown" marker for all three doubles, because a positional
+ * doubles array cannot hold a null and `0` is a real value for every one of them
+ * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
+ */
+export const TELEMETRY_POINT_VERSION = 1;
+const INDEX_MAX_BYTES = 96;
+/**
+ * Truncate to at most `maxBytes` UTF-8 bytes without splitting a code point —
+ * `String.slice` counts UTF-16 units, so a route with one multi-byte character
+ * can be ≤96 chars and still exceed the 96-BYTE index limit.
+ */
+function truncateUtf8(value, maxBytes) {
+    const encoded = new TextEncoder().encode(value);
+    if (encoded.length <= maxBytes)
+        return value;
+    return new TextDecoder('utf-8', { fatal: false }).decode(encoded.subarray(0, maxBytes)).replace(
+    // A cut through a multi-byte sequence decodes to U+FFFD; drop that trailing artefact.
+    /�+$/, '');
+}
+const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : -1;
+/** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
+export function toDataPoint(event) {
+    const route = event.route ?? '';
+    return {
+        indexes: [truncateUtf8(route, INDEX_MAX_BYTES)],
+        blobs: [event.method ?? '', route, event.userId ?? ''],
+        doubles: [num(event.status), num(event.durationMs), num(event.bytesOut)],
+    };
+}
+/**
+ * Build the sink for whatever platform this process is on.
+ *
+ * Throws when NEITHER backend is available, on purpose. "An app with no
+ * `request_metrics` is not quiet; it is unmeasured" — and a sink that silently
+ * drops every event is exactly the failure this seam exists to end. A misbound
+ * Worker should fail at construction, in the deploy, rather than serve traffic
+ * that nothing can see.
+ */
+export function createTelemetrySink(opts) {
+    const { analytics, db, flushIntervalMs, maxSize } = opts;
+    if (analytics) {
+        // Analytics Engine writes are fire-and-forget and already off the response
+        // path — there is nothing to buffer, so flush/stop are honestly no-ops.
+        return {
+            record(event) {
+                analytics.writeDataPoint(toDataPoint(event));
+            },
+            flush() { },
+            stop() { },
+            get size() {
+                return 0;
+            },
+        };
+    }
+    if (!db) {
+        throw new Error('createTelemetrySink: neither an Analytics Engine binding (`analytics`) nor a `db` was ' +
+            'provided. Telemetry would be silently dropped; bind one of the two.');
+    }
+    // The unchanged SQLite path — same module, same batching, same rows.
+    return createMetricsBuffer({ db, flushIntervalMs, maxSize });
+}

package/dist/server/middleware/index.d.ts

@@ -4,6 +4,7 @@ export { errorEnvelope } from './errorEnvelope';
 export { crossOriginRefusal } from './localOrigin';
 export { clientIp, createRateLimiter, type RateLimitOpts } from './rateLimit';
 export { type RequestLoggerOpts, requestLogger } from './requestLogger';
+export { type AnalyticsEngineDataset, createTelemetrySink, type TelemetryEvent, type TelemetrySink, type TelemetrySinkOptions, } from '../metrics/telemetrySink';
 export { type CspDirectives, type SecurityHeadersOpts, securityHeaders, } from './securityHeaders';
 export { toValidationIssues, VALIDATION_ERROR_CODE, type ValidationIssue, validationEnvelope, } from '../errors';
 export { type ZValidatorTarget, zValidator } from './zValidator';

package/dist/server/middleware/index.js

@@ -5,6 +5,9 @@ export { errorEnvelope } from './errorEnvelope';
 export { crossOriginRefusal } from './localOrigin';
 export { clientIp, createRateLimiter } from './rateLimit';
 export { requestLogger } from './requestLogger';
+// The telemetry seam `requestLogger` writes through — re-exported here so a caller
+// that reaches `./middleware` for the logger can bind Analytics Engine in the same import.
+export { createTelemetrySink, } from '../metrics/telemetrySink';
 export { securityHeaders, } from './securityHeaders';
 export { toValidationIssues, VALIDATION_ERROR_CODE, validationEnvelope, } from '../errors';
 export { zValidator } from './zValidator';

package/dist/server/middleware/requestLogger.d.ts

@@ -1,29 +1,48 @@
 import type { Database } from 'bun:sqlite';
 import type { MiddlewareHandler } from 'hono';
 import type { CursedbeltEnv } from '../context';
-import { type MetricsBuffer } from '../metrics/metricsBuffer';
+import type { MetricsBuffer } from '../metrics/metricsBuffer';
+import { type AnalyticsEngineDataset, type TelemetrySink } from '../metrics/telemetrySink';
 /**
- * Structured request/response logging. After each request it records one slim
- * `request_metrics` row (via the batched {@link MetricsBuffer}, off the hot path)
- * and, for errors (status ≥ 400) or slow requests, one `event_logs` row tagged with
- * the correlation id. Attributes rows to `c.get('userId')` when the app's auth
+ * Structured request/response logging. After each request it records one
+ * telemetry event through the {@link TelemetrySink} (off the hot path) and, for
+ * errors (status ≥ 400) or slow requests, one `event_logs` row tagged with the
+ * correlation id. Attributes rows to `c.get('userId')` when the app's auth
  * middleware has set it.
  *
+ * 🔴 **Where the telemetry LANDS is the sink's decision, not this file's.** With
+ * an Analytics Engine binding it is one `writeDataPoint` and **zero** database
+ * rows; without one it is the same batched `request_metrics` insert it has always
+ * been. See `../metrics/telemetrySink.ts` for why that is the only choice offered.
+ *
  * It records metrics even when a downstream handler THROWS: the error is caught,
- * the would-be status derived, the row written, then the error re-thrown so the
+ * the would-be status derived, the event recorded, then the error re-thrown so the
  * error-envelope `onError` still produces the response.
  */
 export interface RequestLoggerOpts {
     /**
-     * The metrics buffer to write through. Provide one (and own its lifecycle via
-     * `buffer.stop()`) to share it / flush deterministically; omit to create one from
-     * `db`. Its flush timer is `unref()`'d, so an internally-created buffer is fine for
-     * long-running servers.
+     * The Analytics Engine binding, when the platform supplies one. Present ⇒ the
+     * telemetry goes there and NOTHING is written to `request_metrics`.
+     */
+    analytics?: AnalyticsEngineDataset | null;
+    /**
+     * The sink to write through. Provide one (and own its lifecycle via
+     * `sink.stop()`) to share it / flush deterministically; omit to build one from
+     * `db` + `analytics`. A {@link MetricsBuffer} is a valid sink.
      */
+    sink?: TelemetrySink;
+    /** @deprecated Use {@link RequestLoggerOpts.sink} — a `MetricsBuffer` is one. Kept for callers that predate the sink. */
     buffer?: MetricsBuffer;
     /** Duration (ms) at/above which a 2xx request also logs an `event_logs` row. Default: 2000. */
     slowMs?: number;
     /** Also write `event_logs` rows for status ≥ 400. Default: true. */
     logErrors?: boolean;
 }
-export declare function requestLogger(db: Database, opts?: RequestLoggerOpts): MiddlewareHandler<CursedbeltEnv>;
+/**
+ * @param db The `request_metrics` / `event_logs` database. Pass `null` on a
+ *   platform that has no `bun:sqlite` — a Worker with `analytics` bound — in
+ *   which case `event_logs` is not written either, because there is nowhere to
+ *   put it. `analytics` or `sink` is then mandatory; `createTelemetrySink`
+ *   throws rather than drop telemetry silently.
+ */
+export declare function requestLogger(db: Database | null, opts?: RequestLoggerOpts): MiddlewareHandler<CursedbeltEnv>;

package/dist/server/middleware/requestLogger.js

@@ -1,7 +1,7 @@
 import { HTTPException } from 'hono/http-exception';
 import { isApiError } from '../errors';
-import { createMetricsBuffer } from '../metrics/metricsBuffer';
 import { normalizeRoute } from '../metrics/normalizeRoute';
+import { createTelemetrySink, } from '../metrics/telemetrySink';
 function statusOfThrown(err) {
     if (isApiError(err))
         return err.status;
@@ -9,13 +9,22 @@ function statusOfThrown(err) {
         return err.status;
     return 500;
 }
+/**
+ * @param db The `request_metrics` / `event_logs` database. Pass `null` on a
+ *   platform that has no `bun:sqlite` — a Worker with `analytics` bound — in
+ *   which case `event_logs` is not written either, because there is nowhere to
+ *   put it. `analytics` or `sink` is then mandatory; `createTelemetrySink`
+ *   throws rather than drop telemetry silently.
+ */
 export function requestLogger(db, opts = {}) {
-    const buffer = opts.buffer ?? createMetricsBuffer({ db });
+    const sink = opts.sink ?? opts.buffer ?? createTelemetrySink({ db, analytics: opts.analytics ?? null });
     const slowMs = opts.slowMs ?? 2000;
     const logErrors = opts.logErrors ?? true;
-    const insertEvent = db.prepare(`INSERT INTO event_logs
+    const insertEvent = db
+        ? db.prepare(`INSERT INTO event_logs
        (id, correlation_id, event_name, type, message, details, duration_ms, user_id, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        : null;
     return async (c, next) => {
         const start = performance.now();
         let thrown;
@@ -33,10 +42,10 @@ export function requestLogger(db, opts = {}) {
         const lenHeader = didThrow ? null : c.res.headers.get('content-length');
         const bytesOut = lenHeader ? Number(lenHeader) : null;
         const userId = c.get('userId') ?? null;
-        buffer.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
+        sink.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
         const isError = status >= 400;
         const isSlow = durationMs >= slowMs;
-        if ((logErrors && isError) || isSlow) {
+        if (insertEvent && ((logErrors && isError) || isSlow)) {
             const type = status >= 500 ? 'error' : isError ? 'warn' : 'info';
             insertEvent.run(crypto.randomUUID(), c.get('correlationId') ?? null, isError ? 'http_error' : 'http_slow', type, `${method} ${route} → ${status}`, JSON.stringify({ method, route, status, durationMs: Math.round(durationMs), bytesOut }), Math.round(durationMs), userId, new Date().toISOString());
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/server/index.ts

@@ -144,6 +144,15 @@ export {
   type MetricsBufferOptions,
 } from './metrics/metricsBuffer';
 export { normalizeRoute } from './metrics/normalizeRoute';
+export {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  TELEMETRY_POINT_VERSION,
+  type TelemetryEvent,
+  type TelemetrySink,
+  type TelemetrySinkOptions,
+  toDataPoint,
+} from './metrics/telemetrySink';
 // ── Middleware ────────────────────────────────────────────────────────────────
 export { correlationId } from './middleware/correlationId';
 export { type CorsOpts, corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';

package/src/server/metrics/telemetrySink.spec.ts

@@ -0,0 +1,288 @@
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { type RequestLoggerOpts, requestLogger } from '../middleware/requestLogger';
+import { createMetricsBuffer } from './metricsBuffer';
+import {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  type TelemetrySink,
+  toDataPoint,
+} from './telemetrySink';
+
+/**
+ * The two claims the seam makes, and nothing else:
+ *
+ *   1. Analytics Engine bound  → a request writes **ZERO** `request_metrics` rows.
+ *      This is the claim with money behind it: a row per request on D1 is billed
+ *      at $1.00 per million rows written, and "we moved to Analytics Engine" is
+ *      worth nothing if the insert is still firing beside it.
+ *   2. Analytics Engine ABSENT → the SQLite path is byte-for-byte what it is
+ *      today. Proven by running the same request through the sink-backed logger
+ *      and through a hand-built `createMetricsBuffer` — the pre-seam call — and
+ *      comparing every column. The gate and every Mac-hosted app ride on this.
+ */
+
+/** The `request_metrics` / `event_logs` DDL `metricsBuffer` + `requestLogger` write. */
+function schema(db: Database): void {
+  db.run(`CREATE TABLE request_metrics (
+    id TEXT PRIMARY KEY, ts INTEGER NOT NULL, method TEXT, route TEXT,
+    status INTEGER, duration_ms REAL, bytes_out INTEGER, user_id TEXT)`);
+  db.run(`CREATE TABLE event_logs (
+    id TEXT PRIMARY KEY, correlation_id TEXT, event_name TEXT, type TEXT, message TEXT,
+    details TEXT, duration_ms INTEGER, user_id TEXT, created_at TEXT)`);
+}
+
+type Point = Parameters<AnalyticsEngineDataset['writeDataPoint']>[0];
+
+/** A recording stand-in for the platform binding. */
+function fakeDataset(): AnalyticsEngineDataset & { points: Point[] } {
+  const points: Point[] = [];
+  return {
+    points,
+    writeDataPoint(point) {
+      points.push(point);
+    },
+  };
+}
+
+const rows = (db: Database) =>
+  db.query('SELECT * FROM request_metrics ORDER BY ts').all() as Record<string, unknown>[];
+
+describe('createTelemetrySink — Analytics Engine bound means ZERO database rows', () => {
+  let db: Database;
+  beforeEach(() => {
+    db = new Database(':memory:');
+    schema(db);
+  });
+
+  it('writes no request_metrics row for a served request, and one data point instead', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    // 🔴 `db` is passed as well: the binding must WIN over an available database,
+    // not merely work in its absence. A Worker mid-migration has both.
+    app.use('*', requestLogger(db, { analytics: ae }));
+    app.get('/api/people/:id/portrait', (c) => c.text('bytes'));
+
+    expect((await app.request('/api/people/42/portrait')).status).toBe(200);
+
+    // The flush timer would be the only other writer; force it and re-check.
+    await Bun.sleep(5);
+    expect(rows(db)).toHaveLength(0);
+    expect(db.query('SELECT COUNT(*) AS n FROM event_logs').get()).toEqual({ n: 0 });
+
+    expect(ae.points).toHaveLength(1);
+    const [point] = ae.points;
+    expect(point.indexes).toEqual(['/api/people/:id/portrait']);
+    expect(point.blobs?.[0]).toBe('GET');
+    expect(point.blobs?.[1]).toBe('/api/people/:id/portrait');
+    expect(point.doubles?.[0]).toBe(200);
+  });
+
+  it('writes no row for a THROWN request either — the error path is the tempting leak', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    app.use('*', requestLogger(db, { analytics: ae }));
+    app.get('/boom', () => {
+      throw new Error('nope');
+    });
+    app.onError((_e, c) => c.text('handled', 500));
+
+    expect((await app.request('/boom')).status).toBe(500);
+    await Bun.sleep(5);
+
+    expect(rows(db)).toHaveLength(0);
+    expect(ae.points).toHaveLength(1);
+    expect(ae.points[0].doubles?.[0]).toBe(500);
+  });
+
+  it('needs no database at all — the Worker shape, where bun:sqlite does not exist', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    app.use('*', requestLogger(null, { analytics: ae }));
+    app.get('/', (c) => c.text('ok'));
+
+    expect((await app.request('/')).status).toBe(200);
+    expect(ae.points).toHaveLength(1);
+  });
+
+  it('holds nothing locally, so there is no buffer to lose on isolate teardown', () => {
+    const sink = createTelemetrySink({ analytics: fakeDataset(), db: null });
+    sink.record({
+      ts: 1,
+      method: 'GET',
+      route: '/',
+      status: 200,
+      durationMs: 1,
+      bytesOut: 2,
+      userId: null,
+    });
+    expect(sink.size).toBe(0);
+    // flush/stop are honest no-ops, not silent drops — calling them changes nothing.
+    sink.flush();
+    sink.stop();
+    expect(sink.size).toBe(0);
+  });
+
+  it('refuses to construct with neither backend rather than drop telemetry silently', () => {
+    expect(() => createTelemetrySink({ db: null, analytics: null })).toThrow(
+      /neither an Analytics Engine binding/,
+    );
+  });
+});
+
+describe('toDataPoint — the layout is a wire format', () => {
+  it('maps every column to its documented position, with -1 for unknown', () => {
+    expect(
+      toDataPoint({
+        ts: 123,
+        method: 'POST',
+        route: '/api/v1/sync/requested',
+        status: 204,
+        durationMs: 12.5,
+        bytesOut: null,
+        userId: 'u-1',
+      }),
+    ).toEqual({
+      indexes: ['/api/v1/sync/requested'],
+      blobs: ['POST', '/api/v1/sync/requested', 'u-1'],
+      // bytesOut null → -1. `0` is a real value for a 204, so it cannot be the marker.
+      doubles: [204, 12.5, -1],
+    });
+  });
+
+  it('truncates the index to 96 BYTES, not 96 characters', () => {
+    // 60 three-byte characters = 180 bytes, but only 60 UTF-16 units — `slice(0, 96)`
+    // would leave 180 bytes and the platform would reject the data point.
+    const route = `/${'路'.repeat(60)}`;
+    const { indexes, blobs } = toDataPoint({
+      ts: 1,
+      method: 'GET',
+      route,
+      status: 200,
+      durationMs: 1,
+      bytesOut: 1,
+      userId: null,
+    });
+    const bytes = new TextEncoder().encode(indexes[0]).length;
+    expect(bytes).toBeLessThanOrEqual(96);
+    // Not split mid-character: it round-trips, so no U+FFFD was left behind.
+    expect(indexes[0]).toBe(new TextDecoder().decode(new TextEncoder().encode(indexes[0])));
+    expect(indexes[0].includes('�')).toBe(false);
+    // …and blob2 keeps the FULL route, so nothing is actually lost.
+    expect(blobs[1]).toBe(route);
+  });
+
+  it('an anonymous request sends an empty userId blob, never a null hole', () => {
+    const { blobs } = toDataPoint({
+      ts: 1,
+      method: 'GET',
+      route: '/',
+      status: 200,
+      durationMs: 1,
+      bytesOut: 0,
+      userId: null,
+    });
+    expect(blobs[2]).toBe('');
+  });
+});
+
+describe('createTelemetrySink — no binding means the SQLite path, unchanged', () => {
+  /** Columns that are allowed to differ between two identical requests. */
+  const stable = (row: Record<string, unknown>) => {
+    const { id: _id, ts: _ts, duration_ms: _d, ...rest } = row;
+    return rest;
+  };
+
+  it('produces the same row the pre-seam createMetricsBuffer call produces', async () => {
+    const viaSink = new Database(':memory:');
+    const viaBuffer = new Database(':memory:');
+    schema(viaSink);
+    schema(viaBuffer);
+
+    const build = (db: Database, logger: ReturnType<typeof requestLogger>) => {
+      const app = new Hono();
+      app.use('*', logger);
+      // 🔴 `content-length` is set EXPLICITLY. `requestLogger` reads `bytes_out` off
+      // that header and Hono does not add one for a small in-process response, so
+      // without it this test would assert `bytes_out: null` and prove nothing about
+      // the column that actually carries bytes.
+      app.get('/api/player', (c) => c.json({ playing: false }, 200, { 'content-length': '18' }));
+      return { app, db };
+    };
+
+    // The new path: no `analytics`, so the sink resolves to the SQLite buffer.
+    const a = build(viaSink, requestLogger(viaSink));
+    // The pre-seam path, spelled exactly as a caller spelled it before this change.
+    const priorBuffer = createMetricsBuffer({ db: viaBuffer });
+    const b = build(viaBuffer, requestLogger(viaBuffer, { buffer: priorBuffer }));
+
+    expect((await a.app.request('/api/player')).status).toBe(200);
+    expect((await b.app.request('/api/player')).status).toBe(200);
+
+    // Both buffer; both must flush the same way. 1500ms is the shared cadence, so
+    // force it rather than sleep through it.
+    priorBuffer.flush();
+    await Bun.sleep(1700);
+
+    const sinkRows = rows(viaSink);
+    const bufferRows = rows(viaBuffer);
+    expect(sinkRows).toHaveLength(1);
+    expect(bufferRows).toHaveLength(1);
+    expect(stable(sinkRows[0])).toEqual(stable(bufferRows[0]));
+    // Column-by-column, so a renamed or dropped column cannot hide behind a deep-equal.
+    expect(Object.keys(sinkRows[0])).toEqual([
+      'id',
+      'ts',
+      'method',
+      'route',
+      'status',
+      'duration_ms',
+      'bytes_out',
+      'user_id',
+    ]);
+    expect(stable(sinkRows[0])).toEqual({
+      method: 'GET',
+      route: '/api/player',
+      status: 200,
+      bytes_out: 18,
+      user_id: null,
+    });
+    expect(typeof sinkRows[0].duration_ms).toBe('number');
+  });
+
+  it('still buffers rather than writing per request — the latency property is not lost', () => {
+    const db = new Database(':memory:');
+    schema(db);
+    const sink = createTelemetrySink({ db });
+    sink.record({
+      ts: 1,
+      method: 'GET',
+      route: '/',
+      status: 200,
+      durationMs: 1,
+      bytesOut: 0,
+      userId: null,
+    });
+    // Buffered, NOT written: `size` is 1 and the table is still empty.
+    expect(sink.size).toBe(1);
+    expect(rows(db)).toHaveLength(0);
+    sink.flush();
+    expect(sink.size).toBe(0);
+    expect(rows(db)).toHaveLength(1);
+    sink.stop();
+  });
+
+  it('a MetricsBuffer satisfies TelemetrySink, so an app can keep passing its own', () => {
+    const db = new Database(':memory:');
+    schema(db);
+    const buffer = createMetricsBuffer({ db });
+    // Structural, and the ASSIGNMENT is the assertion — this line is what would stop
+    // compiling if the two shapes ever diverged, which is why it is typed explicitly.
+    const sink: TelemetrySink = buffer;
+    expect(sink.size).toBe(0);
+    const opts: RequestLoggerOpts = { sink: buffer };
+    expect(opts.sink).toBe(buffer);
+    buffer.stop();
+  });
+});

package/src/server/metrics/telemetrySink.ts

@@ -0,0 +1,181 @@
+import type { Database } from 'bun:sqlite';
+import { createMetricsBuffer, type MetricRow, type MetricsBuffer } from './metricsBuffer';
+
+/**
+ * ONE seam for "this app served a request", with two backends and no third.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * `request_metrics` is a row per request. On D1 that is the one line in
+ * Cloudflare's pricing with a dollar-scale overage — **$1.00 per million rows
+ * written** — and a row per request is precisely the shape that buys it. Workers
+ * Analytics Engine is purpose-built for the same job: `writeDataPoint()` per
+ * event, SQL to query, unlimited cardinality, **10M data points and 1M read
+ * queries included per month**, and **zero** database writes.
+ *
+ * 🔴 **Adopt it for the ALLOWANCE, not because it is unbilled today.**
+ * Cloudflare's own wording is that you "will not be billed for your use of
+ * Workers Analytics Engine" today and that the published prices are "shared in
+ * advance… once Cloudflare starts billing for usage in the coming months". The
+ * free-today part is temporary; the allowance is not. At this fleet's measured
+ * ~1M requests/month the bill is $0 either way, so building against the
+ * allowance makes the billing switch a non-event.
+ *
+ * ── Why not `prom-client` / a `/metrics` scrape ──────────────────────────────
+ * A scrape genuinely does turn many writes into one, and on a long-lived Bun
+ * process it would work. A Worker is **a stateless V8 isolate with no
+ * long-lived process**: isolates are created and destroyed between requests and
+ * run concurrently in many datacentres, so a `/metrics` scrape reaches ONE
+ * arbitrary isolate holding a random fraction of the counters. The in-process
+ * registry has nowhere to live. (A Durable Object does have a durable identity
+ * *and* memory, and is the real `prom-client` analogue — but it is a whole
+ * stateful object to operate for counters Analytics Engine already aggregates.
+ * Prometheus itself also needs an always-on host to scrape FROM, and that host
+ * is the Mac this fleet is trying to switch off.)
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ * · `analytics` bound  → one `writeDataPoint` per event, **zero** SQLite/D1 rows.
+ * · no `analytics`     → the existing {@link MetricsBuffer}, byte-for-byte
+ *                        unchanged, so the gate and a Mac-hosted app keep working.
+ * Both are proven by `telemetrySink.spec.ts`, which is the point of the seam:
+ * the choice is made ONCE here rather than per app.
+ */
+
+/**
+ * The Workers Analytics Engine binding, typed locally so this package needs no
+ * dependency on `@cloudflare/workers-types` (it is a Bun/Hono package, and a
+ * Worker supplies the real binding at runtime).
+ *
+ * Platform limits, which {@link toDataPoint} respects:
+ * **1** index of ≤96 bytes, ≤**20** blobs totalling ≤5120 bytes, ≤**20** doubles.
+ */
+export interface AnalyticsEngineDataset {
+  writeDataPoint(point: {
+    indexes?: (ArrayBuffer | string | null)[];
+    blobs?: (ArrayBuffer | string | null)[];
+    doubles?: number[];
+  }): void;
+}
+
+/** One request's telemetry. Identical to {@link MetricRow} — the seam does not re-shape it. */
+export type TelemetryEvent = MetricRow;
+
+/**
+ * A superset-compatible shape: a {@link MetricsBuffer} IS a `TelemetrySink`, so
+ * an app that already owns a buffer can keep passing it.
+ */
+export interface TelemetrySink {
+  /** Enqueue one request's telemetry. Never blocks the response. */
+  record(event: TelemetryEvent): void;
+  /** Force whatever is pending out now (shutdown + tests). No-op on Analytics Engine. */
+  flush(): void;
+  /** Stop any timer and drain. No-op on Analytics Engine. */
+  stop(): void;
+  /** Events pending locally. Always 0 on Analytics Engine — it has no buffer to hold. */
+  readonly size: number;
+}
+
+export interface TelemetrySinkOptions {
+  /**
+   * The Analytics Engine binding, when the platform supplies one. Present ⇒ it
+   * WINS, and `db` is never written. `null`/`undefined` ⇒ the SQLite path.
+   */
+  analytics?: AnalyticsEngineDataset | null;
+  /** The `request_metrics` database. Required unless `analytics` is bound. */
+  db?: Database | null;
+  /** Flush cadence for the SQLite path, in ms. Default: 1500. Ignored by Analytics Engine. */
+  flushIntervalMs?: number;
+  /** Eager-flush threshold for the SQLite path. Default: 5000. Ignored by Analytics Engine. */
+  maxSize?: number;
+}
+
+/**
+ * 🔴 **The data-point layout is a WIRE FORMAT.** Analytics Engine columns are
+ * positional (`blob1`, `double1`, …), so every saved SQL query breaks if a
+ * position moves. Append only; never reorder, never repurpose.
+ *
+ * ```
+ * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
+ * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
+ * double1 = status          double2 = durationMs             double3 = bytesOut
+ * ```
+ *
+ * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
+ * column, so sending ours would store the same instant twice.
+ *
+ * `-1` is the "unknown" marker for all three doubles, because a positional
+ * doubles array cannot hold a null and `0` is a real value for every one of them
+ * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
+ */
+export const TELEMETRY_POINT_VERSION = 1;
+
+const INDEX_MAX_BYTES = 96;
+
+/**
+ * Truncate to at most `maxBytes` UTF-8 bytes without splitting a code point —
+ * `String.slice` counts UTF-16 units, so a route with one multi-byte character
+ * can be ≤96 chars and still exceed the 96-BYTE index limit.
+ */
+function truncateUtf8(value: string, maxBytes: number): string {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.length <= maxBytes) return value;
+  return new TextDecoder('utf-8', { fatal: false }).decode(encoded.subarray(0, maxBytes)).replace(
+    // A cut through a multi-byte sequence decodes to U+FFFD; drop that trailing artefact.
+    /�+$/,
+    '',
+  );
+}
+
+const num = (value: number | null | undefined): number =>
+  typeof value === 'number' && Number.isFinite(value) ? value : -1;
+
+/** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
+export function toDataPoint(event: TelemetryEvent): {
+  indexes: string[];
+  blobs: string[];
+  doubles: number[];
+} {
+  const route = event.route ?? '';
+  return {
+    indexes: [truncateUtf8(route, INDEX_MAX_BYTES)],
+    blobs: [event.method ?? '', route, event.userId ?? ''],
+    doubles: [num(event.status), num(event.durationMs), num(event.bytesOut)],
+  };
+}
+
+/**
+ * Build the sink for whatever platform this process is on.
+ *
+ * Throws when NEITHER backend is available, on purpose. "An app with no
+ * `request_metrics` is not quiet; it is unmeasured" — and a sink that silently
+ * drops every event is exactly the failure this seam exists to end. A misbound
+ * Worker should fail at construction, in the deploy, rather than serve traffic
+ * that nothing can see.
+ */
+export function createTelemetrySink(opts: TelemetrySinkOptions): TelemetrySink {
+  const { analytics, db, flushIntervalMs, maxSize } = opts;
+
+  if (analytics) {
+    // Analytics Engine writes are fire-and-forget and already off the response
+    // path — there is nothing to buffer, so flush/stop are honestly no-ops.
+    return {
+      record(event) {
+        analytics.writeDataPoint(toDataPoint(event));
+      },
+      flush() {},
+      stop() {},
+      get size() {
+        return 0;
+      },
+    };
+  }
+
+  if (!db) {
+    throw new Error(
+      'createTelemetrySink: neither an Analytics Engine binding (`analytics`) nor a `db` was ' +
+        'provided. Telemetry would be silently dropped; bind one of the two.',
+    );
+  }
+
+  // The unchanged SQLite path — same module, same batching, same rows.
+  return createMetricsBuffer({ db, flushIntervalMs, maxSize });
+}

package/src/server/middleware/index.ts

@@ -5,6 +5,15 @@ export { errorEnvelope } from './errorEnvelope';
 export { crossOriginRefusal } from './localOrigin';
 export { clientIp, createRateLimiter, type RateLimitOpts } from './rateLimit';
 export { type RequestLoggerOpts, requestLogger } from './requestLogger';
+// The telemetry seam `requestLogger` writes through — re-exported here so a caller
+// that reaches `./middleware` for the logger can bind Analytics Engine in the same import.
+export {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  type TelemetryEvent,
+  type TelemetrySink,
+  type TelemetrySinkOptions,
+} from '../metrics/telemetrySink';
 export {
   type CspDirectives,
   type SecurityHeadersOpts,

package/src/server/middleware/requestLogger.ts

@@ -3,28 +3,44 @@ import type { MiddlewareHandler } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import type { CursedbeltEnv } from '../context';
 import { isApiError } from '../errors';
-import { createMetricsBuffer, type MetricsBuffer } from '../metrics/metricsBuffer';
+import type { MetricsBuffer } from '../metrics/metricsBuffer';
 import { normalizeRoute } from '../metrics/normalizeRoute';
+import {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  type TelemetrySink,
+} from '../metrics/telemetrySink';
 
 /**
- * Structured request/response logging. After each request it records one slim
- * `request_metrics` row (via the batched {@link MetricsBuffer}, off the hot path)
- * and, for errors (status ≥ 400) or slow requests, one `event_logs` row tagged with
- * the correlation id. Attributes rows to `c.get('userId')` when the app's auth
+ * Structured request/response logging. After each request it records one
+ * telemetry event through the {@link TelemetrySink} (off the hot path) and, for
+ * errors (status ≥ 400) or slow requests, one `event_logs` row tagged with the
+ * correlation id. Attributes rows to `c.get('userId')` when the app's auth
  * middleware has set it.
  *
+ * 🔴 **Where the telemetry LANDS is the sink's decision, not this file's.** With
+ * an Analytics Engine binding it is one `writeDataPoint` and **zero** database
+ * rows; without one it is the same batched `request_metrics` insert it has always
+ * been. See `../metrics/telemetrySink.ts` for why that is the only choice offered.
+ *
  * It records metrics even when a downstream handler THROWS: the error is caught,
- * the would-be status derived, the row written, then the error re-thrown so the
+ * the would-be status derived, the event recorded, then the error re-thrown so the
  * error-envelope `onError` still produces the response.
  */
 
 export interface RequestLoggerOpts {
   /**
-   * The metrics buffer to write through. Provide one (and own its lifecycle via
-   * `buffer.stop()`) to share it / flush deterministically; omit to create one from
-   * `db`. Its flush timer is `unref()`'d, so an internally-created buffer is fine for
-   * long-running servers.
+   * The Analytics Engine binding, when the platform supplies one. Present ⇒ the
+   * telemetry goes there and NOTHING is written to `request_metrics`.
+   */
+  analytics?: AnalyticsEngineDataset | null;
+  /**
+   * The sink to write through. Provide one (and own its lifecycle via
+   * `sink.stop()`) to share it / flush deterministically; omit to build one from
+   * `db` + `analytics`. A {@link MetricsBuffer} is a valid sink.
    */
+  sink?: TelemetrySink;
+  /** @deprecated Use {@link RequestLoggerOpts.sink} — a `MetricsBuffer` is one. Kept for callers that predate the sink. */
   buffer?: MetricsBuffer;
   /** Duration (ms) at/above which a 2xx request also logs an `event_logs` row. Default: 2000. */
   slowMs?: number;
@@ -38,19 +54,29 @@ function statusOfThrown(err: unknown): number {
   return 500;
 }
 
+/**
+ * @param db The `request_metrics` / `event_logs` database. Pass `null` on a
+ *   platform that has no `bun:sqlite` — a Worker with `analytics` bound — in
+ *   which case `event_logs` is not written either, because there is nowhere to
+ *   put it. `analytics` or `sink` is then mandatory; `createTelemetrySink`
+ *   throws rather than drop telemetry silently.
+ */
 export function requestLogger(
-  db: Database,
+  db: Database | null,
   opts: RequestLoggerOpts = {},
 ): MiddlewareHandler<CursedbeltEnv> {
-  const buffer = opts.buffer ?? createMetricsBuffer({ db });
+  const sink =
+    opts.sink ?? opts.buffer ?? createTelemetrySink({ db, analytics: opts.analytics ?? null });
   const slowMs = opts.slowMs ?? 2000;
   const logErrors = opts.logErrors ?? true;
 
-  const insertEvent = db.prepare(
-    `INSERT INTO event_logs
+  const insertEvent = db
+    ? db.prepare(
+        `INSERT INTO event_logs
        (id, correlation_id, event_name, type, message, details, duration_ms, user_id, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  );
+      )
+    : null;
 
   return async (c, next) => {
     const start = performance.now();
@@ -70,11 +96,11 @@ export function requestLogger(
     const bytesOut = lenHeader ? Number(lenHeader) : null;
     const userId = c.get('userId') ?? null;
 
-    buffer.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
+    sink.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
 
     const isError = status >= 400;
     const isSlow = durationMs >= slowMs;
-    if ((logErrors && isError) || isSlow) {
+    if (insertEvent && ((logErrors && isError) || isSlow)) {
       const type = status >= 500 ? 'error' : isError ? 'warn' : 'info';
       insertEvent.run(
         crypto.randomUUID(),

package/src/shippedFilesAreTracked.spec.ts

@@ -0,0 +1,69 @@
+/**
+ * 🔴 `bun publish` packs the WORKING DIRECTORY, not the git index — so a package can
+ * ship a file the repo does not have.
+ *
+ * ── What this cost, 2026-09-15 ─────────────────────────────────────────────────────
+ * The cursedbelt split (task 148) moved two integration specs into this package from
+ * `cursedbelt`. `git add -u .` stages only files git already knows about, so both were
+ * committed nowhere — and `bun run verify` was green *because they were present on disk*,
+ * which is the same reason nobody noticed. `1.0.2` went to the registry carrying two
+ * `src/` files that existed in no commit, and `git status` said `tracked-dirty=0`.
+ *
+ * "The tree is clean" and "everything that ships is committed" are different claims, and
+ * only the first one is what people actually check. npm versions are immutable, so the
+ * window to notice closes at publish time.
+ *
+ * ── Why this shape ─────────────────────────────────────────────────────────────────
+ * It asks git, for exactly the directories `package.json#files` promises to ship, which
+ * of those paths git does not track. That is narrower than "any untracked file" on
+ * purpose: scratch files, `.agent.noindex/`, a half-written script and an uncommitted
+ * lockfile are all legitimate states for a working tree and reddening on them would teach
+ * people to skip this. A file INSIDE the published surface is the only case where
+ * untracked means "about to ship something no one can review or revert".
+ *
+ * 🔴 It must run from a real checkout to mean anything, so it refuses rather than passes
+ * when `git` cannot answer — a check that silently degrades to green is worse than none.
+ */
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+
+/** The directories `files` promises to ship, minus build output nobody commits. */
+const shippedDirs = (): string[] =>
+	((pkg as { files?: string[] }).files ?? []).filter((f) => f !== 'dist' && existsSync(`${repoRoot}/${f}`));
+
+const git = (...args: string[]): { ok: boolean; out: string } => {
+	const r = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });
+	return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
+};
+
+describe('every file inside the published surface is tracked', () => {
+	test('git can answer at all — a degraded check must refuse, not pass', () => {
+		expect(git('rev-parse', '--is-inside-work-tree').ok, 'not a git checkout, so this check proves nothing').toBe(true);
+	});
+
+	test('package.json names a shippable directory to scan', () => {
+		// Vacuity guard: an empty `files`, or one naming only `dist`, makes the assertion
+		// below pass while scanning nothing at all.
+		expect(shippedDirs().length, '`files` names no committed directory — nothing would be scanned').toBeGreaterThan(0);
+	});
+
+	test('no untracked file sits inside a directory `files` ships', () => {
+		// --others = untracked; --exclude-standard honours .gitignore, so deliberately
+		// ignored paths (.agent.noindex, node_modules) are not offences.
+		const { ok, out } = git('ls-files', '--others', '--exclude-standard', '--', ...shippedDirs());
+		expect(ok, 'git ls-files failed').toBe(true);
+		const untracked = out === '' ? [] : out.split('\n');
+		expect(
+			untracked,
+			'these would be PUBLISHED but exist in no commit — `bun publish` packs the working directory, not the index,\n' +
+				'so the registry would carry code nobody can review, diff or revert, and npm versions are immutable.\n' +
+				'Commit them (or add them to .gitignore if they genuinely must not ship):\n  ' +
+				untracked.join('\n  '),
+		).toEqual([]);
+	});
+});