@vzn/vx-history-server 0.0.0 → 0.0.649

package/Dockerfile

@@ -0,0 +1,22 @@
+# vx-history-server as a container, built from the repo root:
+#   docker build -f packages/vx-history-server/Dockerfile -t vx-history-server .
+#   docker run -p 8080:8080 -v vx-history:/data -e ALLOW='https://token.actions.githubusercontent.com:acme/app:ci.yml' vx-history-server
+# One bundled file: the server and the CI token check it shares with
+# vx's other servers (@vzn/vx-devtools), with jose.
+FROM oven/bun:1.4.4-slim@sha256:1846adf22496bd711036aae8be147e57bdebbaea2e5264e3e0b5af1db187d9a4 AS build
+WORKDIR /repo
+COPY packages/vx-devtools/package.json packages/vx-devtools/
+# jose as @vzn/vx-devtools pins it: the image names no version of its own.
+RUN cd packages/vx-devtools && bun install --production --ignore-scripts
+COPY packages/vx-devtools/src packages/vx-devtools/src/
+COPY packages/vx-history-server/src packages/vx-history-server/src/
+RUN mkdir -p node_modules/@vzn && ln -s ../../packages/vx-devtools node_modules/@vzn/vx-devtools \
+ && bun build packages/vx-history-server/src/bun.ts --target=bun --outfile=/out/vx-history-server.js
+
+FROM oven/bun:1.4.4-slim@sha256:1846adf22496bd711036aae8be147e57bdebbaea2e5264e3e0b5af1db187d9a4
+COPY --from=build /out/vx-history-server.js /app/
+RUN mkdir /data && chown bun /data
+USER bun
+VOLUME /data
+EXPOSE 8080
+ENTRYPOINT ["bun", "--no-env-file", "--no-install", "/app/vx-history-server.js", "--db", "/data/vx-history.sqlite"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VZN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,78 @@
+# vx-history protocol, v1
+
+An HTTP API for the task timings a scheduler asks for. It is a history,
+not a log: a server keeps one row per task and ref, and folds each
+report into it. `@vzn/vx-history-server` speaks it on Bun, on Cloudflare
+Workers and as a Docker image; any server that does can take its place.
+
+| Route                     | What it does                      |
+| ------------------------- | --------------------------------- |
+| `POST /v1/timings/upload` | a run's timings, once at its end  |
+| `POST /v1/timings/query`  | each task's numbers, ready to use |
+| `GET /v1/capabilities`    | the server's limits               |
+
+## Repositories and tokens
+
+A row is keyed by the issuer (the CI issuer's URL, no trailing slash),
+the repository (`org/name` there, lowercased), the ref
+(`refs/heads/main`) and the task's definition hash, each stored plainly.
+
+A request's `Authorization: Bearer <token>` is a CI job's OIDC token,
+checked as `@vzn/vx-devtools` checks it (the same `ALLOW` as
+vx-cache-server's): a repository, or a workflow, `ALLOW` does not name
+is `403`. A token writes its own ref (`refs/heads/<branch>`; a
+`pull_request` run its merge ref, `refs/pull/<n>/merge`, never its
+`head_ref`; a `merge_group` run,
+`refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>`, its base branch); a
+`pull_request_target`, `issue_comment` or `workflow_run` run reads only,
+and so does a GitLab merge request pipeline whose `source_project_path` (GitLab 19.5+)
+does not name its own project. A query names its
+repository; a token of another is `403`. A server whose `READ_ACCESS`
+is `public` takes a query with no token for a repository `ALLOW` names;
+an upload with none is `403`.
+
+## Upload
+
+`POST /v1/timings/upload` (a token that writes) with
+`{ "timings": [{ "hash", "durationMs", "cores"?, "rssBytes"? }] }`, up to
+10 000, each task once: `204`. `hash` names the task's definition, a
+string of up to 512 characters (no lone surrogate) the server never
+reads. Each folds into its row of the token's repository and ref:
+
+- `durationMs` and `cores`: `old × 0.7 + new × 0.3`. A median needs the
+  samples and a mean never forgets; this follows a task that got slower
+  within about three runs, and one outlier moves it 30%.
+- `rssBytes`: `max(new, old × 0.9)`. A reservation needs the peak; the
+  decay lets a task that shrank come down.
+- `runs`: how many reports moved the row.
+
+A report that would not move the row (`durationMs` and `cores` within
+5%, no new `rssBytes` peak) is not written, unless the row is a day old:
+each write costs, and the fold would move it under 1.5%.
+
+The first report sets the row; one without `cores` or `rssBytes` keeps
+the row's. A row not reported for `TIMING_DAYS` (30) is deleted.
+
+## Query
+
+One request a run: `POST /v1/timings/query` with
+`{ "issuer", "repository", "refs": ["refs/heads/feature", "refs/heads/main"], "hashes": [ … ] }`,
+1 to 8 refs and up to 10 000 hashes: each hash's row in the first ref
+named that holds one. A hash none holds is absent. The numbers are the
+scheduler's as they are:
+
+```json
+{ "timings": { "3b0d…": { "durationMs": 4200, "cores": 1.8, "rssBytes": 310000000, "runs": 12 } } }
+```
+
+## Limits and errors
+
+`GET /v1/capabilities`: `{ "maxUploadTimings": 10000, "maxQueryHashes": 10000, "maxQueryRefs": 8 }`.
+A server takes both at their limits, each hash 512 characters: an
+upload body up to 7 120 000 bytes, a query's up to 6 010 000. Past
+that, `413`.
+
+Every refusal is `{ code, message }`, the message saying what to fix. A
+JSON body without `Content-Type: application/json` is `400`, an unknown
+route `404`, a route's wrong method `405` with `Allow`, a failure the
+server did not expect `500`, its `message` what failed.

package/README.md

@@ -1,3 +1,90 @@
 # @vzn/vx-history-server
 
-Placeholder. Part of [vx](https://github.com/vznjs/vx).
+Website: <https://vznjs.github.io/vx/> · source: <https://github.com/vznjs/vx>
+
+A server for the task timings a vx scheduler asks for, that you host. It
+keeps one row per task, already the numbers the scheduler uses (duration,
+CPU cores, peak memory), and merges each CI run's report into it: a
+history, not a log. It speaks the [vx-history protocol](./PROTOCOL.md)
+(`/v1`) on three backends that answer alike:
+
+- **Bun**, with a SQLite file.
+- **Cloudflare Workers**, with D1. It fits the free plan: an upload is one
+  statement per 2 MB of reports, a row write per task; a query one read
+  per 2 MB of hashes.
+- **Docker**, the Bun server in an image.
+
+`vxHistory()` ([`@vzn/vx-history`](https://github.com/vznjs/vx/tree/main/packages/vx-history))
+points vx at it.
+
+## CI tokens
+
+Every request carries a CI job's own OIDC token, checked by `@vzn/vx-devtools`,
+under the same `ALLOW` as [`@vzn/vx-cache-server`'s](https://github.com/vznjs/vx/tree/main/packages/vx-cache-server#ci-tokens)
+(`issuer:owner/repo:workflow` entries): a job of a workflow it names
+writes its own branch, and any other job is refused. A row is the issuer,
+repository, ref and task hash, stored plainly, and its numbers. A run
+sends one query: its repository, the refs it reads (its branch, then the
+branch it merges into, then the default branch) and every task hash;
+the server answers each from the first ref that holds it. A token of
+another repository than the query names is refused. `AUDIENCE` is the
+`aud` a token must name: the origin clients reach the server at. On
+Workers, unset, it is that origin (Cloudflare routes only the Worker's
+own hostnames to it); on Bun and Docker it is required, since there the
+origin is the request's `Host` header, which a client picks.
+`READ_ACCESS=public` lets a query with no token read a repository
+`ALLOW` names; it uploads nothing.
+
+## On Bun
+
+```sh
+ALLOW='https://token.actions.githubusercontent.com:acme/app:ci.yml' AUDIENCE=https://history.example.com bun packages/vx-history-server/src/bun.ts --db /var/lib/vx-history.sqlite --port 8080
+```
+
+`TIMING_DAYS` (default 30, whole days in decimal digits; on Workers a JSON number too)
+is how long a task's row outlives its last report; the first upload of each day sweeps, whichever node or Workers
+isolate takes it.
+
+## With Docker
+
+From the repo root:
+
+```sh
+docker build -f packages/vx-history-server/Dockerfile -t vx-history-server .
+docker run -p 8080:8080 -v vx-history:/data -e ALLOW='…' -e AUDIENCE=https://history.example.com vx-history-server
+```
+
+The database is `/data/vx-history.sqlite`.
+
+With vx's other servers: [`compose.yaml`](https://github.com/vznjs/vx/blob/main/private/vx-servers/compose.yaml)
+builds and runs all three (`docker compose up -d`).
+
+## On Cloudflare Workers
+
+From this directory, with `ALLOW` filled in `wrangler.jsonc`:
+
+```sh
+bun install
+bunx wrangler login
+bunx wrangler deploy
+```
+
+The Worker reads its D1 database as the binding `DB`, as `wrangler.jsonc`
+names it.
+
+## API
+
+The same server as a `fetch` handler, over storage of your own
+(`src/index.ts`):
+
+- `createHistoryServer(options: ServerOptions)` returns
+  `(req: Request) => Promise<Response>`. `ServerOptions` is
+  `{ store, authorize, timingDays?, now? }`: `authorize` is
+  `oidcTokenAuth` from `@vzn/vx-devtools`.
+- `sqliteStore(db: Db)` is the `Store` over a SQLite `Db`
+  (`{ all(sql, params), run(sql, params) }`), as bun:sqlite and D1 are.
+  A `Store` merges `Report`s and reads `Timing`s, each of a `Repo`
+  (`{ issuer, repository }`) and a ref.
+- `WEIGHT` (0.3) and `RSS_DECAY` (0.9) are the merge's constants;
+  `MAX_UPLOAD_TIMINGS`, `MAX_QUERY_HASHES` and `MAX_QUERY_REFS` its
+  limits. A refusal is `errorJson` from `@vzn/vx-devtools`.

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by `<pkg>/index.ts` and ignore package.json `exports` / `main`
+// (see packages/vx/index.ts). Same module as the exports map names.
+export * from './src/index.js'

package/package.json

@@ -1,8 +1,57 @@
 {
   "name": "@vzn/vx-history-server",
-  "version": "0.0.0",
-  "description": "Placeholder; real releases are published by CI.",
+  "version": "0.0.649",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/vznjs/vx.git" },
-  "publishConfig": { "access": "public" }
+  "description": "The task timings a vx scheduler asks for, one folded row per task, that you host: on Bun with SQLite, on Cloudflare Workers with D1, or as a Docker image.",
+  "keywords": [
+    "vx",
+    "monorepo",
+    "scheduler",
+    "history-server"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "vx-history-server": "./src/bun.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "import": "./src/worker.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "PROTOCOL.md",
+    "wrangler.jsonc",
+    "Dockerfile",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "//": [
+    "@vzn/vx: vx.config.ts's core; `*`, not workspace:, which npm refuses when a deploy installs this directory alone.",
+    "@vzn/vx-devtools: checks the CI tokens, the check vx's servers share (it imports only jose); `*` for the same reason.",
+    "wrangler: deploys src/worker.ts by wrangler.jsonc.",
+    "jose: the tests sign the CI tokens the server checks.",
+    "miniflare: tests/worker.test.ts runs src/worker.ts in workerd with D1, as Workers deploy it."
+  ],
+  "dependencies": {
+    "@vzn/vx-devtools": "0.0.649"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-history-server"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-history-server#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
 }

package/src/bun.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env -S bun --no-env-file --no-install
+// `vx-history-server` on Bun: the timings in one SQLite file (PROTOCOL.md,
+// README.md).
+
+import { Database } from 'bun:sqlite'
+import { parseArgs } from 'node:util'
+import { oidcTokenAuth, parseAllow, statusLine } from '@vzn/vx-devtools'
+import { timingDaysOf } from './days.js'
+import { createHistoryServer } from './server.js'
+import { type Db, sqliteStore } from './store.js'
+
+const USAGE = `usage: vx-history-server [--db vx-history.sqlite] [--port 8080] [--host 0.0.0.0]
+  ALLOW        who may take part, space separated, each issuer:owner/repo:workflow
+               (README.md § CI tokens); only their jobs' OIDC tokens are taken
+  AUDIENCE     the aud a CI token names: the URL clients reach this server at
+  READ_ACCESS  public: a request with no token reads a repository ALLOW names
+  TIMING_DAYS  days a task's timings outlive its last report (default 30)`
+
+/** A SQLite file through bun:sqlite. */
+export function sqliteDb(path: string): Db {
+  const db = new Database(path, { create: true, strict: true })
+  db.run('PRAGMA journal_mode = WAL')
+  db.run('PRAGMA busy_timeout = 5000')
+  return {
+    all: async <T>(sql: string, params: readonly unknown[]) =>
+      db.query(sql).all(...(params as never[])) as T[],
+    run: async (sql, params) => db.query(sql).run(...(params as never[])).changes,
+  }
+}
+
+function main(argv: string[]): void {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      db: { type: 'string', default: 'vx-history.sqlite' },
+      port: { type: 'string', default: '8080' },
+      host: { type: 'string', default: '0.0.0.0' },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  })
+  if (values.help) {
+    console.log(USAGE)
+    return
+  }
+  const env = Bun.env
+  // Digits only: Number('') is 0, a random port for `--port "$PORT"` with
+  // PORT unset, and Number read 0x50 as 80 and 1e1 as 10.
+  const port = /^\d+$/.test(values.port) ? Number(values.port) : Number.NaN
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    fail(`--port: not a port: ${values.port}`)
+  // Bun.serve reads '' as localhost: unreachable from another host or container.
+  if (values.host.trim() === '') fail(`--host: needs an address, got '${values.host}'`)
+  let allow
+  let timingDays
+  try {
+    allow = parseAllow(env.ALLOW ?? '')
+  } catch (err) {
+    fail(`ALLOW: ${(err as Error).message}`)
+  }
+  // An empty one started a server that refused every request.
+  if (allow.length === 0) fail(`set ALLOW\n${USAGE}`)
+  try {
+    timingDays = timingDaysOf(env.TIMING_DAYS)
+  } catch (err) {
+    fail((err as Error).message)
+  }
+  // bun:sqlite opens '' as a temporary database: every timing was gone at
+  // the next restart, and nothing said so.
+  if (values.db === '') fail(`--db: needs a file path, got ''\n${USAGE}`)
+  let db
+  try {
+    db = sqliteDb(values.db)
+  } catch (err) {
+    // SQLite's own message ("unable to open database file") named no path.
+    fail(`--db ${values.db}: ${(err as Error).message}`)
+  }
+  // Unset, the audience would be the origin a request names: its Host
+  // header, which the client picks. Workers know their own hostnames.
+  const audience = env.AUDIENCE?.trim() ?? ''
+  if (audience === '')
+    fail(`set AUDIENCE: the aud a CI token names, the URL clients reach this server at\n${USAGE}`)
+  const handle = createHistoryServer({
+    store: sqliteStore(db),
+    authorize: oidcTokenAuth({
+      allow,
+      readAccess: env.READ_ACCESS,
+      audience,
+    }),
+    ...(timingDays === undefined ? {} : { timingDays }),
+  })
+  const server = Bun.serve({ hostname: values.host, port, fetch: handle })
+  process.stdout.write(statusLine('ok', 'vx-history-server', `listening on ${server.url.href}`))
+  const stop = (): void => void server.stop().then(() => process.exit(0))
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+}
+
+function fail(message: string): never {
+  process.stderr.write(statusLine('err', 'vx-history-server', message))
+  process.exit(2)
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (err) {
+    // parseArgs names the flag it refused, not the ones there are.
+    const usage = (err as { code?: string }).code?.startsWith('ERR_PARSE_ARGS') ? `\n${USAGE}` : ''
+    fail(`${err instanceof Error ? err.message : String(err)}${usage}`)
+  }
+}

package/src/days.ts

@@ -0,0 +1,24 @@
+// `TIMING_DAYS`, as Bun's environment and Workers' vars both name it.
+
+/**
+ * `TIMING_DAYS`: a whole number of days, or undefined for the default. A
+ * Worker var may be JSON: a number is read as Bun reads its decimal digits, and
+ * anything else is refused, as `TIMING_DAYS=true` is on Bun (`true` was
+ * read as 1 day).
+ */
+export function timingDaysOf(value: unknown): number | undefined {
+  if (value === undefined || value === '') return undefined
+  // A string is digits only, as --port is: Number read 0x1e as 30.
+  const days =
+    typeof value === 'number'
+      ? value
+      : typeof value === 'string' && /^\d+$/.test(value)
+        ? Number(value)
+        : Number.NaN
+  if (!Number.isSafeInteger(days) || days < 1) {
+    throw new Error(
+      `TIMING_DAYS: a whole number of days, got ${typeof value === 'string' || typeof value === 'number' ? value : JSON.stringify(value)}`,
+    )
+  }
+  return days
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// @vzn/vx-history-server: the task timings a vx scheduler asks for, one
+// folded row per task, on Bun with SQLite or on Cloudflare Workers with D1.
+
+export {
+  createHistoryServer,
+  MAX_QUERY_HASHES,
+  MAX_QUERY_REFS,
+  MAX_UPLOAD_TIMINGS,
+  type ServerOptions,
+} from './server.js'
+export {
+  type Db,
+  type Report,
+  type Repo,
+  RSS_DECAY,
+  sqliteStore,
+  type Store,
+  type Timing,
+  WEIGHT,
+} from './store.js'

package/src/server.ts

@@ -0,0 +1,236 @@
+// The vx-history protocol, v1 (PROTOCOL.md), as one fetch handler over a
+// `Store`: Bun and Workers serve the same one.
+
+import { type Access, errorJson, notAllowed, Refusal } from '@vzn/vx-devtools'
+import type { Report, Repo, Store } from './store.js'
+
+/** Reports one upload folds in: a run's tasks. */
+export const MAX_UPLOAD_TIMINGS = 10_000
+/** Hashes one query names. */
+export const MAX_QUERY_HASHES = 10_000
+/** Refs one query names, read in order. */
+export const MAX_QUERY_REFS = 8
+const MAX_STRING = 512
+/** A report's bytes at most: its hash at `MAX_STRING`, its numbers at their longest. */
+const MAX_REPORT_BYTES = MAX_STRING + 200
+const DAY_MS = 86_400_000
+
+export interface ServerOptions {
+  readonly store: Store
+  /** A request's verified token, checked against the repository it names (`oidcTokenAuth`). */
+  readonly authorize: (req: Request, named?: Repo) => Promise<Access | undefined>
+  /** Days a task's row outlives its last report (default 30). */
+  readonly timingDays?: number
+  /** Milliseconds since the epoch; tests move the clock. */
+  readonly now?: () => number
+}
+
+/** A full ref, as a token names one. */
+const REF = /^refs\/\S+$/
+
+export function createHistoryServer(opts: ServerOptions): (req: Request) => Promise<Response> {
+  const { store, authorize } = opts
+  const now = opts.now ?? Date.now
+  let ready: Promise<void> | undefined
+  const schema = (): Promise<void> =>
+    (ready ??= store.init().catch((err: unknown) => {
+      ready = undefined
+      throw err
+    }))
+  const capabilities = {
+    maxUploadTimings: MAX_UPLOAD_TIMINGS,
+    maxQueryHashes: MAX_QUERY_HASHES,
+    maxQueryRefs: MAX_QUERY_REFS,
+  }
+
+  // The fold is one upsert, a few ms for a thousand tasks: done inline (2026-10-25).
+  async function upload(req: Request): Promise<Response> {
+    const access = await authorize(req)
+    if (access?.write === undefined) throw new Refusal(403, 'this request reads only')
+    const reports = parseReports(await readJson(req, MAX_UPLOAD_TIMINGS * MAX_REPORT_BYTES))
+    await schema()
+    await store.fold(access, access.write, now(), reports)
+    return new Response(null, { status: 204 })
+  }
+
+  // One request a run: every hash, each answered from the first ref that holds it.
+  async function query(req: Request): Promise<Response> {
+    // No token, or a bad one, is refused before the body is read.
+    await authorize(req)
+    const body = await readJson(req, MAX_QUERY_HASHES * 600 + 10_000)
+    const issuer = field(body, 'issuer')
+    const repository = field(body, 'repository')
+    const refs = field(body, 'refs')
+    const hashes = field(body, 'hashes')
+    if (
+      typeof issuer !== 'string' ||
+      !/^https?:\/\/\S+$/.test(issuer) ||
+      issuer.length > MAX_STRING
+    )
+      throw new Refusal(400, "issuer: the CI issuer's URL, as its tokens name it")
+    if (
+      typeof repository !== 'string' ||
+      !/^[^/\s]+(\/[^/\s]+)+$/.test(repository) ||
+      repository.length > MAX_STRING
+    )
+      throw new Refusal(400, 'repository: org/name at the issuer')
+    if (
+      !Array.isArray(refs) ||
+      refs.length === 0 ||
+      refs.length > MAX_QUERY_REFS ||
+      !refs.every((r) => typeof r === 'string' && REF.test(r) && r.length <= MAX_STRING)
+    ) {
+      throw new Refusal(
+        400,
+        `refs: 1 to ${MAX_QUERY_REFS} full refs (refs/heads/main), read in order`,
+      )
+    }
+    if (
+      !Array.isArray(hashes) ||
+      hashes.length > MAX_QUERY_HASHES ||
+      !hashes.every((h) => isOpaque(h))
+    ) {
+      throw new Refusal(400, `hashes: a list of up to ${MAX_QUERY_HASHES} strings`)
+    }
+    const repo = (await authorize(req, { issuer, repository }))!
+    await schema()
+    const rows = await store.read(repo, refs as string[], hashes as string[])
+    return Response.json({ timings: Object.fromEntries(rows) })
+  }
+
+  let swept = 0
+  // At most one sweep a day, on an upload: no timer, no cron. Each node
+  // asks the database when any node last swept, once a day: a Worker's
+  // isolates each swept the whole table on their first upload. A failed
+  // sweep fails no upload, which is folded by then; the next tries again.
+  const sweep = async (): Promise<void> => {
+    const t = now()
+    if (t - swept < DAY_MS) return
+    swept = t
+    try {
+      const last = await store.sweptAt()
+      if (t - last < DAY_MS) {
+        swept = last
+        return
+      }
+      await store.sweep(t - (opts.timingDays ?? 30) * DAY_MS, t)
+    } catch (err) {
+      swept = 0
+      console.error(`vx-history-server: the sweep: ${String(err)}`)
+    }
+  }
+
+  return async (req) => {
+    const path = new URL(req.url).pathname
+    try {
+      const search = new URL(req.url).search
+      if (search !== '')
+        throw new Refusal(
+          400,
+          `this server takes no query parameters: drop ${search.slice(0, 200)} from the url`,
+        )
+      if (path === '/v1/timings/upload') {
+        if (req.method !== 'POST') return notAllowed('POST')
+        const res = await upload(req)
+        await sweep()
+        return res
+      }
+      if (path === '/v1/timings/query') {
+        return req.method === 'POST' ? await query(req) : notAllowed('POST')
+      }
+      if (path === '/v1/capabilities') {
+        if (req.method !== 'GET') return notAllowed('GET')
+        await authorize(req)
+        return Response.json(capabilities)
+      }
+      return errorJson(
+        404,
+        `no route ${req.method} ${path.slice(0, 200)}: name the server's base URL; it serves /v1/ (PROTOCOL.md)`,
+      )
+    } catch (err) {
+      if (err instanceof Refusal) return errorJson(err.status, err.message)
+      // Never swallowed: the client warns with what the server says.
+      console.error(`vx-history-server: ${req.method} ${path}: ${String(err)}`)
+      return errorJson(500, err instanceof Error ? err.message : String(err))
+    }
+  }
+}
+
+const field = (body: unknown, key: string): unknown =>
+  typeof body === 'object' && body !== null ? (body as Record<string, unknown>)[key] : undefined
+
+// A lone surrogate is stored as bytes that read back as U+FFFD: the row
+// answers to a hash no client asked for.
+const isOpaque = (s: unknown): s is string =>
+  typeof s === 'string' && s.length > 0 && s.length <= MAX_STRING && !/\p{Cs}/u.test(s)
+
+const isCount = (n: unknown): n is number =>
+  typeof n === 'number' && Number.isSafeInteger(n) && n >= 0
+
+async function readJson(req: Request, max: number): Promise<unknown> {
+  if (!/^application\/json\b/i.test(req.headers.get('content-type') ?? '')) {
+    throw new Refusal(400, 'send the body as Content-Type: application/json')
+  }
+  if (Number(req.headers.get('content-length') ?? 0) > max) {
+    throw new Refusal(413, `the body is at most ${max} bytes`)
+  }
+  const text = await textUpTo(req, max)
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Refusal(400, 'the body is not JSON')
+  }
+}
+
+/** A run's reports, as the store folds them: unknown fields are dropped. */
+function parseReports(body: unknown): Report[] {
+  const list = field(body, 'timings')
+  if (!Array.isArray(list) || list.length > MAX_UPLOAD_TIMINGS) {
+    throw new Refusal(400, `timings: a list of up to ${MAX_UPLOAD_TIMINGS}`)
+  }
+  const seen = new Set<string>()
+  return list.map((x: unknown, i): Report => {
+    const bad = (what: string): never => {
+      throw new Refusal(400, `timings[${i}].${what}`)
+    }
+    const hash = field(x, 'hash')
+    const durationMs = field(x, 'durationMs')
+    const cores = field(x, 'cores')
+    const rssBytes = field(x, 'rssBytes')
+    if (!isOpaque(hash)) bad(`hash: a string of up to ${MAX_STRING} characters`)
+    // One row per task: a second report of it in one upload would fold twice.
+    if (seen.has(hash as string)) bad('hash: each task once')
+    seen.add(hash as string)
+    if (!isCount(durationMs)) bad('durationMs: whole milliseconds')
+    if (
+      cores !== undefined &&
+      !(typeof cores === 'number' && Number.isFinite(cores) && cores >= 0)
+    ) {
+      bad('cores: a number of cores')
+    }
+    if (rssBytes !== undefined && !isCount(rssBytes)) bad('rssBytes: a byte count')
+    return {
+      hash: hash as string,
+      durationMs: durationMs as number,
+      ...(cores === undefined ? {} : { cores: cores as number }),
+      ...(rssBytes === undefined ? {} : { rssBytes: rssBytes as number }),
+    }
+  })
+}
+
+/**
+ * The body as text, refused past `max` bytes as they arrive: a chunked body
+ * names no length, and was read whole before it was measured.
+ */
+async function textUpTo(req: Request, max: number): Promise<string> {
+  const decoder = new TextDecoder()
+  let text = ''
+  let seen = 0
+  // Leaving the loop by a throw cancels the stream.
+  for await (const chunk of req.body ?? []) {
+    seen += chunk.byteLength
+    if (seen > max) throw new Refusal(413, `the body is at most ${max} bytes`)
+    text += decoder.decode(chunk, { stream: true })
+  }
+  return text + decoder.decode()
+}

package/src/store.ts

@@ -0,0 +1,178 @@
+// What the server keeps: one row per issuer, repository, ref and task
+// definition, already the numbers a scheduler asks for (2026-10-25: a
+// history, not a log). Each report folds into its row in one statement, so
+// racing jobs lose nothing. Every column is plain (2026-10-27): the
+// server is the user's own, and a hash only hid its rows from them.
+
+/** A SQLite database, as bun:sqlite and D1 both serve one. */
+export interface Db {
+  all<T>(sql: string, params: readonly unknown[]): Promise<T[]>
+  run(sql: string, params: readonly unknown[]): Promise<number>
+}
+
+/** One run of a task that succeeded, as a client reports it. */
+export interface Report {
+  /** The task's definition hash, opaque to the server. */
+  readonly hash: string
+  readonly durationMs: number
+  /** CPU cores it kept busy on average. */
+  readonly cores?: number
+  /** Its peak memory. */
+  readonly rssBytes?: number
+}
+
+/** What a scheduler reads for a task: the folded numbers and how many runs made them. */
+export interface Timing {
+  readonly durationMs: number
+  readonly cores: number | null
+  readonly rssBytes: number | null
+  readonly runs: number
+}
+
+/**
+ * The newest run's weight in a task's duration and cores: a median needs
+ * the samples, a plain mean never forgets; at 0.3 a task that truly got
+ * slower is followed within about three runs, and one outlier moves it 30%.
+ */
+export const WEIGHT = 0.3
+/** Peak memory keeps the larger of the new peak and the old one decayed by this: a reservation needs the peak. */
+export const RSS_DECAY = 0.9
+
+/**
+ * A report within this share of the row (and no new memory peak) leaves
+ * it as it is, unless the row is a day old: the fold would move it under
+ * 1.5%, and each write is billed (D1's free plan: 100k rows a day). The
+ * day keeps a reported task's row past the sweep; `runs` counts the
+ * reports that moved it.
+ */
+const NOISE = 0.05
+const DAY_MS = 86_400_000
+
+/** A repository: its issuer's URL, no trailing slash, and its `org/name` there, lowercased. */
+export interface Repo {
+  readonly issuer: string
+  readonly repository: string
+}
+
+// 2026-10-27: rows were keyed by hashes of these; nothing that table
+// holds can be read by plain values.
+const DROP_OLD = 'DROP TABLE IF EXISTS task_timings'
+const SCHEMA = `CREATE TABLE IF NOT EXISTS timings (issuer TEXT NOT NULL, repository TEXT NOT NULL, ref TEXT NOT NULL, hash TEXT NOT NULL, duration_ms INTEGER NOT NULL, cores REAL, rss_bytes INTEGER, runs INTEGER NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY (issuer, repository, ref, hash)) WITHOUT ROWID`
+
+// When the database was last swept, by whichever node: a Worker runs many
+// isolates and starts new ones all day, and each swept on its first upload.
+const SWEEPS =
+  'CREATE TABLE IF NOT EXISTS sweeps (id INTEGER PRIMARY KEY CHECK (id = 1), at INTEGER NOT NULL)'
+
+// One statement per 2 MB of a report's rows, passed as one JSON parameter:
+// D1 binds at most 100 parameters, and a free plan's Worker runs at most
+// 50 queries a request.
+const FOLD = `INSERT INTO timings (issuer, repository, ref, hash, duration_ms, cores, rss_bytes, runs, updated_at)
+SELECT ?1, ?2, ?3, j.value ->> '$.hash', j.value ->> '$.durationMs', j.value ->> '$.cores', j.value ->> '$.rssBytes', 1, ?4
+FROM json_each(?5) AS j WHERE true
+ON CONFLICT (issuer, repository, ref, hash) DO UPDATE SET
+  duration_ms = CAST(round(duration_ms * ${1 - WEIGHT} + excluded.duration_ms * ${WEIGHT}) AS INTEGER),
+  cores = CASE WHEN excluded.cores IS NULL THEN cores WHEN cores IS NULL THEN excluded.cores
+    ELSE cores * ${1 - WEIGHT} + excluded.cores * ${WEIGHT} END,
+  rss_bytes = CASE WHEN excluded.rss_bytes IS NULL THEN rss_bytes WHEN rss_bytes IS NULL THEN excluded.rss_bytes
+    ELSE max(excluded.rss_bytes, CAST(rss_bytes * ${RSS_DECAY} AS INTEGER)) END,
+  runs = runs + 1,
+  updated_at = excluded.updated_at
+WHERE abs(excluded.duration_ms - duration_ms) > duration_ms * ${NOISE}
+  OR (excluded.cores IS NOT NULL AND (cores IS NULL OR abs(excluded.cores - cores) > cores * ${NOISE}))
+  OR (excluded.rss_bytes IS NOT NULL AND (rss_bytes IS NULL OR excluded.rss_bytes > rss_bytes))
+  OR excluded.updated_at - updated_at >= ${DAY_MS}`
+
+/** The rows of `refs` for the hashes asked; a hash the first ref lacks reads the next. */
+const READ = `SELECT hash, ref, duration_ms, cores, rss_bytes, runs FROM timings
+WHERE issuer = ?1 AND repository = ?2 AND ref IN (SELECT value FROM json_each(?3)) AND hash IN (SELECT value FROM json_each(?4))`
+
+export interface Store {
+  init(): Promise<void>
+  /** Folds each report into its row of `ref`. */
+  fold(repo: Repo, ref: string, now: number, reports: readonly Report[]): Promise<void>
+  /** Each hash's row in the first of `refs` that holds one. */
+  read(repo: Repo, refs: readonly string[], hashes: readonly string[]): Promise<Map<string, Timing>>
+  /** When a node last swept the database; 0 before the first sweep. */
+  sweptAt(): Promise<number>
+  /** Deletes the rows not reported since `before`, and records the sweep at `now`; how many. */
+  sweep(before: number, now: number): Promise<number>
+}
+
+/**
+ * D1's limit on a bound string (developers.cloudflare.com/d1/platform/limits):
+ * a report's rows, or a query's hashes, past it failed the statement, so a
+ * server took less than its PROTOCOL.md limits name.
+ */
+const MAX_PARAM_BYTES = 2_000_000
+
+/** `items` as JSON arrays each within `MAX_PARAM_BYTES`: a UTF-16 unit is at most 3 UTF-8 bytes. */
+function jsonParams(items: readonly unknown[]): string[] {
+  const out: string[] = []
+  let part: string[] = []
+  let units = 2
+  for (const item of items) {
+    const json = JSON.stringify(item)
+    if (part.length > 0 && (units + json.length + 1) * 3 > MAX_PARAM_BYTES) {
+      out.push(`[${part.join(',')}]`)
+      part = []
+      units = 2
+    }
+    part.push(json)
+    units += json.length + 1
+  }
+  if (part.length > 0) out.push(`[${part.join(',')}]`)
+  return out
+}
+
+export function sqliteStore(db: Db): Store {
+  return {
+    async init() {
+      await db.run(DROP_OLD, [])
+      await db.run(SCHEMA, [])
+      await db.run(SWEEPS, [])
+    },
+    async fold(repo, ref, now, reports) {
+      for (const part of jsonParams(reports))
+        await db.run(FOLD, [repo.issuer, repo.repository, ref, now, part])
+    },
+    async read(repo, refs, hashes) {
+      const rows = (
+        await Promise.all(
+          jsonParams(hashes).map((part) =>
+            db.all<{
+              hash: string
+              ref: string
+              duration_ms: number
+              cores: number | null
+              rss_bytes: number | null
+              runs: number
+            }>(READ, [repo.issuer, repo.repository, JSON.stringify(refs), part]),
+          ),
+        )
+      ).flat()
+      // A hash's row in the earliest ref asked wins.
+      rows.sort((a, b) => refs.indexOf(b.ref) - refs.indexOf(a.ref))
+      return new Map(
+        rows.map((r) => [
+          r.hash,
+          { durationMs: r.duration_ms, cores: r.cores, rssBytes: r.rss_bytes, runs: r.runs },
+        ]),
+      )
+    },
+    async sweptAt() {
+      const [row] = await db.all<{ at: number }>('SELECT at FROM sweeps WHERE id = 1', [])
+      return row?.at ?? 0
+    },
+    async sweep(before, now) {
+      // A report that would not move its row is not written for up to a
+      // day (FOLD): a row's write time lags its last report by up to that.
+      const deleted = await db.run('DELETE FROM timings WHERE updated_at < ?1', [before - DAY_MS])
+      await db.run(
+        'INSERT INTO sweeps (id, at) VALUES (1, ?1) ON CONFLICT (id) DO UPDATE SET at = excluded.at',
+        [now],
+      )
+      return deleted
+    },
+  }
+}

package/src/worker.ts

@@ -0,0 +1,104 @@
+// `vx-history-server` on Cloudflare Workers, the timings in D1.
+// `wrangler.jsonc` deploys it; ALLOW, AUDIENCE, READ_ACCESS and TIMING_DAYS
+// are vars in it.
+
+import { errorJson, oidcTokenAuth, parseAllow } from '@vzn/vx-devtools'
+import { timingDaysOf } from './days.js'
+import { createHistoryServer } from './server.js'
+import { type Db, sqliteStore } from './store.js'
+
+/** The parts of the Workers runtime this file uses, so it needs no types package. */
+interface D1Statement {
+  bind(...values: unknown[]): D1Statement
+  all<T>(): Promise<{ results: T[] }>
+  run(): Promise<{ meta: { changes: number } }>
+}
+export interface D1Database {
+  prepare(sql: string): D1Statement
+}
+
+export interface Env {
+  readonly DB?: D1Database
+  /** Who may take part (`parseAllow`): `issuer:owner/repo:workflow` entries, space separated. */
+  readonly ALLOW?: string
+  /** The `aud` a CI token names; unset, the origin the Worker is reached at. */
+  readonly AUDIENCE?: string
+  /** `public`: a request with no token reads a repository ALLOW names. */
+  readonly READ_ACCESS?: string
+  /** Days a task's timings outlive its last report (default 30). */
+  readonly TIMING_DAYS?: string | number
+}
+
+function d1Db(d1: D1Database): Db {
+  return {
+    all: async <T>(sql: string, params: readonly unknown[]) =>
+      (
+        await d1
+          .prepare(sql)
+          .bind(...params)
+          .all<T>()
+      ).results,
+    run: async (sql, params) =>
+      (
+        await d1
+          .prepare(sql)
+          .bind(...params)
+          .run()
+      ).meta.changes,
+  }
+}
+
+/** One handler per isolate and settings: the schema is made once per isolate. */
+let made: { key: string; handle: (req: Request) => Promise<Response> } | undefined
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    // A deploy's mistake: unbound, capabilities answered and every upload failed.
+    if (env.DB === undefined) {
+      return errorJson(500, 'DB: bind a D1 database as DB (wrangler.jsonc d1_databases)')
+    }
+    const key = [env.ALLOW, env.AUDIENCE, env.READ_ACCESS, env.TIMING_DAYS].join('\0')
+    if (made?.key !== key) {
+      let allow
+      // wrangler.jsonc may write a var as JSON: a list reached parseAllow.
+      if (env.ALLOW !== undefined && typeof env.ALLOW !== 'string') {
+        return errorJson(
+          500,
+          'ALLOW: one string of issuer:owner/repo:workflow entries, space separated',
+        )
+      }
+      // Likewise AUDIENCE: "env.AUDIENCE.trim is not a function".
+      if (env.AUDIENCE !== undefined && typeof (env.AUDIENCE as unknown) !== 'string') {
+        return errorJson(500, 'AUDIENCE: one string, the aud CI tokens name')
+      }
+      try {
+        allow = parseAllow(env.ALLOW ?? '')
+      } catch (err) {
+        return errorJson(500, `ALLOW: ${(err as Error).message}`)
+      }
+      let authorize
+      let timingDays
+      try {
+        timingDays = timingDaysOf(env.TIMING_DAYS)
+        authorize = oidcTokenAuth({
+          allow,
+          readAccess: env.READ_ACCESS,
+          // jose matches aud exactly: a pasted newline refused every
+          // token as the wrong audience.
+          ...(env.AUDIENCE ? { audience: env.AUDIENCE.trim() } : {}),
+        })
+      } catch (err) {
+        return errorJson(500, (err as Error).message)
+      }
+      made = {
+        key,
+        handle: createHistoryServer({
+          store: sqliteStore(d1Db(env.DB)),
+          authorize,
+          ...(timingDays === undefined ? {} : { timingDays }),
+        }),
+      }
+    }
+    return made.handle(req)
+  },
+}

package/wrangler.jsonc

@@ -0,0 +1,17 @@
+// vx-history-server on Cloudflare Workers (src/worker.ts): `bunx wrangler
+// deploy` from this directory. The timings live in D1.
+{
+  "name": "vx-history-server",
+  "main": "src/worker.ts",
+  "compatibility_date": "2026-10-01",
+  "workers_dev": true,
+  // ALLOW: who may take part, issuer:owner/repo:workflow entries
+  // separated by spaces (README.md § CI tokens); empty, every request is
+  // refused with "set ALLOW". AUDIENCE: the aud a
+  // CI token names, unset the Worker's own origin. READ_ACCESS: public
+  // lets a query with no token read a repository ALLOW names. TIMING_DAYS:
+  // days a task's timings outlive its last report (default 30), a string
+  // or a number.
+  "vars": { "ALLOW": "" },
+  "d1_databases": [{ "binding": "DB", "database_name": "vx-history" }],
+}