diff --git a/AGENTS.md b/AGENTS.md index c25648f..99f79da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,10 @@ a laptop. - `src/github.js`: the GitHub Actions webhook check, the fields it keeps, and the pull queue (pure, tested). - `src/usage.js`: what `/ingest/usage` and `/ingest/limits` accept (`cleanUsage`, `cleanLimits`) and how `/usage/data` sums usage per Halifax day (pure, tested); the `Usage` Durable Object (SQLite, migration `v2`; - `seat_limits` is created in code) is in `src/worker.js`. Private: never route it to the Hub. + `seat_limits` is created in code) is in `src/worker.js`. Private: never route it to the Hub. Its seats are + the employees in `src/hq-registry.json`, plus polaris, codex and other. +- `scripts/copy-hq-registry.mjs`: writes `src/hq-registry.json` from setkernel/hq `registry/people.csv` + (setkernel-live#96): each employee who isn't removed, handles only (`--check` compares). - `src/watch.js`: when to post "updates stopped" and "updates resumed" to Buzz (pure, tested). - `src/buzz.js`: signs and posts a Buzz message as the Worker's own identity (tested). - `src/evidence.js`: the v4 showcase's publisher (setkernel-live#52), a public pull request's evidence and @@ -136,6 +139,8 @@ a laptop. (set only in `ci.yml`) a failed request fails it; elsewhere, including the deploy's re-gate (no token), it skips. A repo the page names that isn't on that list fails it. `evidence.json` is regenerated by `build.mjs --fetch` and goes through `publishEvidence`; never edit it by hand. +- `src/hq-registry.json` is written only by `scripts/copy-hq-registry.mjs`; never edit it by hand, and never + copy more than handles into it (no logins, ids, names or emails: this repo is public). - vitest stays on 4.1.x for now: with vitest 5.0.4, `@cloudflare/vitest-plugin` 1.4.0 fails every suite ("no such file or directory, readAll …/.vitest-cache/…"). - In worker tests, read every response body. An unread body keeps the request open, and diff --git a/README.md b/README.md index d0501b4..c4fc8f5 100644 --- a/README.md +++ b/README.md @@ -224,20 +224,25 @@ Hours older than 400 days are deleted on each push. checks `INGEST_AUD` again. Body (up to 256 KiB): `{ "buckets": [{ "hour": "2026-10-14T15", "seat": "vega", "model": "claude-opus-5-5", "surface": "vm", "input": 0, "output": 0, "cache_read": 0, "cache_write": 0, "usd_micros": 0, "requests": 0 }] }`. `hour` is a UTC hour; - seat is one of vega, rigel, lyra, orion, polaris, codex, other; surface one of vm, desktop, cli, + seat is an employee in `src/hq-registry.json` (below), polaris, codex or other; surface one of vm, desktop, cli, cloud, codex; the counts are whole numbers from 0. One bad bucket makes the whole push 400. A bucket pushed again replaces the stored one, so a pusher can resend an hour's running totals. The answer is `{ stored, days }`: what is now stored for the hours pushed, per Halifax day and seat. - `POST /ingest/limits` (setkernel-live#88) takes each seat's newest 5-hour and weekly limit readings, behind the same Access app and `INGEST_AUD` check: `{ "vega": { "five_hour": { "utilization": 0.84, "resets_at": "…", "observed_at": "…" }, "seven_day": { … }, "event": { "status": "rejected", - "rate_limit_type": "five_hour", "resets_at": "…", "received_at": "…" } } }`. The seats are vega, rigel, - lyra, orion and polaris (Codex has no Claude limits); `utilization` is a fraction from 0; times are + "rate_limit_type": "five_hour", "resets_at": "…", "received_at": "…" } } }`. The seats are the + registry copy's employees and polaris (Codex has no Claude limits); `utilization` is a fraction from 0; times are ISO 8601 with a zone (`resets_at` may be null: unknown); `status` is allowed, allowed_warning or rejected; any part may be null or left out, and changes nothing then. Other fields are dropped; a bad seat, value or time makes the whole push 400. The store (`seat_limits`, one row per seat and part) keeps a part only if it is as new as or newer than the one it has, and answers `{ limits }`: every seat's as now stored. +- The employees are a copy of setkernel/hq's `registry/people.csv` (setkernel-live#96): each employee + who isn't removed, as the wall gives them a lane, handles only. A person added or removed there + needs no code edit here, only a fresh copy: `node scripts/copy-hq-registry.mjs --hq `, + then commit `src/hq-registry.json` (`--check` exits 1 when the committed copy differs). Never edit + it by hand. - `GET /usage/data?month=YYYY-MM` needs a token for its own Access app, checked against `USAGE_AUD` (the "live usage" Access app, setkernel-cloudflare#119; its tag is in `wrangler.jsonc`). With no login Access answers 302 to its login page; if `USAGE_AUD` were ever empty the Worker would diff --git a/scripts/copy-hq-registry.mjs b/scripts/copy-hq-registry.mjs new file mode 100644 index 0000000..3d1c473 --- /dev/null +++ b/scripts/copy-hq-registry.mjs @@ -0,0 +1,66 @@ +// Copies who works here from the hq registry (setkernel/hq registry/people.csv) into src/hq-registry.json +// (setkernel-live#96, setkernel/hq#1089), so the usage ingest's seats (src/usage.js) are no hand-written list. +// Handles only: this repo is public, so no logins, ids, names or emails. The same people the wall gives a lane +// (hq observability/wall/server.py's lanes()): each employee who isn't removed, in the file's order. +// +// node scripts/copy-hq-registry.mjs --hq write the file +// node scripts/copy-hq-registry.mjs --check --hq exit 1 when the committed file differs +// +// Exit 0: written, or no difference. 1: the registry can't be read or the file differs. 2: bad usage. +import { readFileSync, writeFileSync } from "node:fs"; +import { dirname, join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +export const OUT = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "hq-registry.json"); +const HANDLE = /^[a-z][a-z0-9-]{0,31}$/; // hq registry/naming.md's handle; a row with anything else is left out + +// The registry has no quoted fields; a quote is refused rather than half-parsed. +export function parseCsv(text) { + const lines = text.split(/\r?\n/).filter((l) => l.trim() !== ""); + if (lines.length === 0) throw new Error("empty csv"); + if (text.includes('"')) throw new Error("quoted csv fields are not supported"); + const head = lines[0].split(","); + for (const h of ["handle", "kind", "status"]) if (!head.includes(h)) throw new Error(`no ${h} column`); + return lines.slice(1).map((l) => { + const cells = l.split(","); + if (cells.length !== head.length) throw new Error(`row has ${cells.length} fields, header has ${head.length}`); + return Object.fromEntries(head.map((h, i) => [h, cells[i].trim()])); + }); +} + +// people.csv's text -> the canonical text of src/hq-registry.json. +export function render(peopleCsv) { + const employees = []; + for (const r of parseCsv(peopleCsv)) { + if (r.kind === "employee" && r.status !== "removed" && HANDLE.test(r.handle) && !employees.includes(r.handle)) employees.push(r.handle); + } + return JSON.stringify({ employees }, null, 2) + "\n"; +} + +function main(argv) { + const i = argv.indexOf("--hq"); + const hq = i >= 0 ? argv[i + 1] : undefined; + if (!hq) { + console.error("usage: copy-hq-registry.mjs [--check] --hq "); + return 2; + } + let text; + try { + text = render(readFileSync(join(hq, "registry", "people.csv"), "utf8")); + } catch (e) { + console.error(`copy-hq-registry: ${e.message}`); + return 1; + } + if (argv.includes("--check")) { + let have = null; + try { have = readFileSync(OUT, "utf8"); } catch { /* missing counts as differing */ } + if (have === text) return 0; + console.error("copy-hq-registry: src/hq-registry.json differs from the hq registry"); + return 1; + } + writeFileSync(OUT, text); + return 0; +} + +// Not import.meta.main: that needs Node 24.2 (scripts/smoke.mjs says the same). +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2)); diff --git a/src/hq-registry.json b/src/hq-registry.json new file mode 100644 index 0000000..efb01a5 --- /dev/null +++ b/src/hq-registry.json @@ -0,0 +1,8 @@ +{ + "employees": [ + "vega", + "rigel", + "lyra", + "orion" + ] +} diff --git a/src/usage.js b/src/usage.js index 674606c..df3648b 100644 --- a/src/usage.js +++ b/src/usage.js @@ -3,8 +3,13 @@ // Usage Durable Object keeps them apart from the Hub, so no public route can return them. Pure and // tested (test/usage.test.mjs); the Durable Object is in src/worker.js. import { homeDay } from "../public/lib/state.js"; +import registry from "./hq-registry.json" with { type: "json" }; -export const SEATS = ["vega", "rigel", "lyra", "orion", "polaris", "codex", "other"]; +// Who may push usage (setkernel-live#96): each employee in the hq registry's copy (written by +// scripts/copy-hq-registry.mjs, never by hand), then the seats that are no one there: polaris (Raghav's +// own sessions), codex and other. A person added to or removed from the registry needs no code edit. +export const usageSeats = (employees) => [...employees, "polaris", "codex", "other"]; +export const SEATS = usageSeats(registry.employees); export const SURFACES = ["vm", "desktop", "cli", "cloud", "codex"]; export const COUNTS = ["input", "output", "cache_read", "cache_write", "usd_micros", "requests"]; export const KEEP_DAYS = 400; @@ -23,12 +28,12 @@ export const hourOf = (ms) => new Date(ms).toISOString().slice(0, 13); // { buckets: [{ hour, seat, model, surface, input, output, cache_read, cache_write, usd_micros, // requests }] } -> the buckets with only those fields, or null if any of them is not allowed. -export function cleanUsage(body) { +export function cleanUsage(body, seats = SEATS) { if (!body || typeof body !== "object" || !Array.isArray(body.buckets)) return null; const out = []; for (const b of body.buckets) { if (!b || typeof b !== "object") return null; - if (Number.isNaN(hourMs(b.hour)) || !SEATS.includes(b.seat) || !SURFACES.includes(b.surface)) return null; + if (Number.isNaN(hourMs(b.hour)) || !seats.includes(b.seat) || !SURFACES.includes(b.surface)) return null; if (typeof b.model !== "string" || !MODEL.test(b.model)) return null; if (!COUNTS.every((k) => Number.isSafeInteger(b[k]) && b[k] >= 0)) return null; out.push({ hour: b.hour, seat: b.seat, model: b.model, surface: b.surface, ...Object.fromEntries(COUNTS.map((k) => [k, b[k]])) }); @@ -39,7 +44,8 @@ export function cleanUsage(body) { // Each seat's 5-hour and weekly limit windows (setkernel-live#88): the newest reading per seat, pushed // to POST /ingest/limits and read back as `limits` from GET /usage/data, in the shape // public/usage/limits.js reads. Codex has no Claude limits, and "other" is no seat, so neither has any. -export const LIMIT_SEATS = SEATS.filter((s) => s !== "codex" && s !== "other"); +export const limitSeats = (employees) => usageSeats(employees).filter((s) => s !== "codex" && s !== "other"); +export const LIMIT_SEATS = limitSeats(registry.employees); export const WINDOWS = ["five_hour", "seven_day"]; export const STATUSES = ["allowed", "allowed_warning", "rejected"]; const ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(?:Z|[+-](\d{2}):(\d{2}))$/; @@ -72,15 +78,15 @@ function cleanEvent(e) { return resets_at === undefined || !received_at ? undefined : { status: e.status, rate_limit_type: e.rate_limit_type, resets_at, received_at }; } -// { : { five_hour, seven_day, event } } -> the same with only LIMIT_SEATS, each window's +// { : { five_hour, seven_day, event } } -> the same with only the seats given (LIMIT_SEATS), each window's // utilization (a fraction, 0.84), resets_at and observed_at, and the event's status, rate_limit_type, // resets_at and received_at, times as toISOString() gives them and a missing part null; or null if any // seat, window or event is not allowed. Fields it doesn't name are dropped. -export function cleanLimits(body) { +export function cleanLimits(body, seats = LIMIT_SEATS) { if (!plain(body)) return null; const out = {}; for (const [seat, s] of Object.entries(body)) { - if (!LIMIT_SEATS.includes(seat) || !plain(s)) return null; + if (!seats.includes(seat) || !plain(s)) return null; const five_hour = cleanWindow(s.five_hour), seven_day = cleanWindow(s.seven_day), event = cleanEvent(s.event); if (five_hour === undefined || seven_day === undefined || event === undefined) return null; out[seat] = { five_hour, seven_day, event }; diff --git a/test/usage.test.mjs b/test/usage.test.mjs index 96d8858..614860b 100644 --- a/test/usage.test.mjs +++ b/test/usage.test.mjs @@ -2,7 +2,9 @@ import { test } from "node:test"; import assert from "node:assert/strict"; import { COUNTS, SEATS, SURFACES, cleanUsage, hourMs, keepFrom, monthRange, sumByDay } from "../src/usage.js"; -import { LIMIT_SEATS, cleanLimits, isoTime } from "../src/usage.js"; +import { LIMIT_SEATS, cleanLimits, isoTime, limitSeats, usageSeats } from "../src/usage.js"; +import { render } from "../scripts/copy-hq-registry.mjs"; +import registry from "../src/hq-registry.json" with { type: "json" }; const bucket = (extra = {}) => ({ hour: "2026-10-14T15", seat: "vega", model: "claude-opus-5-5", surface: "vm", input: 10, output: 20, cache_read: 30, cache_write: 40, usd_micros: 50, requests: 1, ...extra }); const counts = (n) => Object.fromEntries(COUNTS.map((k) => [k, n])); @@ -26,6 +28,39 @@ test("cleanUsage refuses the whole push for any bad bucket", () => { for (const body of [null, [], "x", {}, { buckets: {} }, { buckets: [null] }, { buckets: ["x"] }]) assert.equal(cleanUsage(body), null, JSON.stringify(body)); }); +// A scratch registry/people.csv, in hq's columns, with made-up logins and ids. +const people = (...rows) => ["handle,kind,github_login,github_id,status,persona,lane", "boss,owner,boss-login,1,active,no,", ...rows].join("\n") + "\n"; +const employee = (handle, status = "active", n = 2) => `${handle},employee,${handle}-login,${n},${status},yes,`; + +test("the seats are the registry copy's employees, then polaris, codex and other; anyone else is refused", () => { + assert.deepEqual(Object.keys(registry), ["employees"], "handles only: this repo is public"); + assert.ok(registry.employees.length > 0 && registry.employees.every((h) => /^[a-z][a-z0-9-]{0,31}$/.test(h)), JSON.stringify(registry)); + assert.deepEqual(SEATS, [...registry.employees, "polaris", "codex", "other"]); + assert.deepEqual(LIMIT_SEATS, [...registry.employees, "polaris"]); + const stranger = registry.employees.join("-").slice(0, 31) + "x"; // a handle the copy doesn't hold, whoever it holds + assert.equal(cleanUsage({ buckets: [bucket({ seat: stranger })] }), null, stranger); + assert.equal(cleanLimits({ [stranger]: {} }), null, stranger); +}); + +test("a fifth employee row in a scratch registry copy is a seat with no code change; owner and removed rows are not", () => { + const csv = people(employee("vega"), employee("rigel"), employee("lyra"), employee("orion"), employee("vela"), employee("nova", "removed"), employee("pax", "paused")); + const { employees } = JSON.parse(render(csv)); + assert.deepEqual(employees, ["vega", "rigel", "lyra", "orion", "vela", "pax"]); + assert.ok(!render(csv).includes("login"), "no logins or ids in the copy"); + assert.deepEqual(cleanUsage({ buckets: [bucket({ seat: "vela" })] }, usageSeats(employees)), [bucket({ seat: "vela" })]); + assert.deepEqual(cleanLimits({ vela: {} }, limitSeats(employees)), { vela: { five_hour: null, seven_day: null, event: null } }); + for (const s of ["nova", "boss", "Vela"]) { + assert.equal(cleanUsage({ buckets: [bucket({ seat: s })] }, usageSeats(employees)), null, s); + assert.equal(cleanLimits({ [s]: {} }, limitSeats(employees)), null, s); + } + assert.equal(cleanLimits({ codex: {} }, limitSeats(employees)), null); + // A row that isn't a plain handle is left out, and the same handle twice counts once. + assert.deepEqual(JSON.parse(render(people(employee("vega"), employee("Bad Name"), employee("vega")))).employees, ["vega"]); + for (const bad of ["", 'handle,kind,status\n"vega",employee,active\n', "handle,kind,status\nvega,employee\n", "handle,kind\nvega,employee\n"]) { + assert.throws(() => render(bad), JSON.stringify(bad)); + } +}); + const win = (extra = {}) => ({ utilization: 0.84, resets_at: "2026-11-04T16:10:00.000Z", observed_at: "2026-11-04T14:55:00.000Z", ...extra }); const ev = (extra = {}) => ({ status: "rejected", rate_limit_type: "five_hour", resets_at: "2026-11-04T16:10:00.000Z", received_at: "2026-11-04T14:47:00.000Z", ...extra }); const seat = (extra = {}) => ({ five_hour: win(), seven_day: win({ utilization: 0.52 }), event: ev(), ...extra });