@verdict-ai/api 0.0.0-stage → 0.2.0

package/dist/rate-limit.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Request limits for the hub's open doors (docs/design/hub.md H6): sign-in, publishing, and public reads. A limiter
+ * answers whether one more request under a key is allowed. The in-memory limiter counts per process (per isolate on
+ * Workers) and is a floor; on Cloudflare, bind the Workers Rate Limiting API to share counts across isolates.
+ */
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+export interface RateLimiter {
+    limit(key: string): Promise<boolean> | boolean;
+}
+/** `login`: per client address. `publish` (preview included): per account. `read`: public JSON and pages, per client address. */
+export interface HubLimits {
+    login?: RateLimiter;
+    publish?: RateLimiter;
+    read?: RateLimiter;
+}
+export interface Rule {
+    limit: number;
+    windowMs: number;
+}
+export declare const DEFAULT_HUB_RULES: Record<keyof HubLimits, Rule>;
+/** Fixed-window counter. Old windows are dropped as the map grows, so memory stays bounded by active keys. */
+export declare function memoryLimiter({ limit, windowMs }: Rule, now?: () => number): RateLimiter;
+export declare function defaultHubLimits(now?: () => number): Required<HubLimits>;
+/** Cloudflare's Workers Rate Limiting binding (`[[ratelimits]]` in wrangler.toml). */
+export interface CloudflareRateLimit {
+    limit(options: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+export declare const cloudflareLimiter: (binding: CloudflareRateLimit) => RateLimiter;
+/**
+ * The client a request comes from. Only a header the platform sets is trusted (Cloudflare's `cf-connecting-ip`), or the
+ * socket address the Node server passes in; X-Forwarded-For is anyone's to write.
+ */
+export type ClientKey = (c: Context) => string;
+export declare const defaultClientKey: ClientKey;
+/** Answered as 429 with Retry-After by the app's error handler. */
+export declare class RateLimitedError extends HTTPException {
+    constructor(what: string);
+}
+export declare function enforce(limiter: RateLimiter | undefined, key: string, what: string): Promise<void>;

package/dist/rate-limit.js

@@ -0,0 +1,40 @@
+import { HTTPException } from "hono/http-exception";
+export const DEFAULT_HUB_RULES = {
+    login: { limit: 10, windowMs: 60_000 },
+    publish: { limit: 30, windowMs: 60_000 },
+    read: { limit: 300, windowMs: 60_000 },
+};
+/** Fixed-window counter. Old windows are dropped as the map grows, so memory stays bounded by active keys. */
+export function memoryLimiter({ limit, windowMs }, now = Date.now) {
+    const windows = new Map();
+    return {
+        limit(key) {
+            const t = now();
+            if (windows.size > 10_000)
+                for (const [k, w] of windows)
+                    if (t - w.start >= windowMs)
+                        windows.delete(k);
+            const w = windows.get(key);
+            if (!w || t - w.start >= windowMs) {
+                windows.set(key, { start: t, count: 1 });
+                return true;
+            }
+            w.count++;
+            return w.count <= limit;
+        },
+    };
+}
+export function defaultHubLimits(now) {
+    return { login: memoryLimiter(DEFAULT_HUB_RULES.login, now), publish: memoryLimiter(DEFAULT_HUB_RULES.publish, now), read: memoryLimiter(DEFAULT_HUB_RULES.read, now) };
+}
+export const cloudflareLimiter = (binding) => ({ limit: async (key) => (await binding.limit({ key })).success });
+export const defaultClientKey = (c) => c.req.header("cf-connecting-ip") ?? "anonymous";
+/** Answered as 429 with Retry-After by the app's error handler. */
+export class RateLimitedError extends HTTPException {
+    constructor(what) { super(429, { message: `too many ${what} requests; try again in a minute` }); }
+}
+export async function enforce(limiter, key, what) {
+    if (limiter && !(await limiter.limit(key)))
+        throw new RateLimitedError(what);
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQpD,MAAM,CAAC,MAAM,iBAAiB,GAAkC;IAC9D,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IACtC,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IACxC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE;CACvC,CAAC;AAEF,8GAA8G;AAC9G,MAAM,UAAU,aAAa,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAQ,EAAE,MAAoB,IAAI,CAAC,GAAG;IACnF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4C,CAAC;IACpE,OAAO;QACL,KAAK,CAAC,GAAG;YACP,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC;YAChB,IAAI,OAAO,CAAC,IAAI,GAAG,MAAM;gBAAE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO;oBAAE,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,QAAQ;wBAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACxG,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,QAAQ,EAAE,CAAC;gBAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;gBAAC,OAAO,IAAI,CAAC;YAAC,CAAC;YAC7F,CAAC,CAAC,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAkB;IACjD,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;AAC1K,CAAC;AAKD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAA4B,EAAe,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAOnJ,MAAM,CAAC,MAAM,gBAAgB,GAAc,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,WAAW,CAAC;AAElG,mEAAmE;AACnE,MAAM,OAAO,gBAAiB,SAAQ,aAAa;IACjD,YAAY,IAAY,IAAI,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,YAAY,IAAI,kCAAkC,EAAE,CAAC,CAAC,CAAC,CAAC;CAC3G;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAgC,EAAE,GAAW,EAAE,IAAY;IACvF,IAAI,OAAO,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC"}

package/dist/routes/admin.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { AppOptions, Env } from "../app.js";
+/** Registers admin operations; handler failures propagate to the transport error boundary. */
+export declare function registerAdmin(app: Hono<Env>, { engine, keys, adminKey, now }: AppOptions): void;

package/dist/routes/admin.js

@@ -0,0 +1,81 @@
+/**
+ * Defines admin request handling at the REST boundary.
+ * Tenant context flows to every engine/store operation; validation failures use the shared HTTP error mapper.
+ */
+import { hasPublications, NotFoundError, ValidationError } from "@verdict-ai/core";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+/** Registers admin operations; handler failures propagate to the transport error boundary. */
+export function registerAdmin(app, { engine, keys, adminKey, now = () => Date.now() }) {
+    app.use("/v1/admin/*", async (c, next) => {
+        if (!adminKey)
+            throw new HTTPException(404, { message: "admin API disabled (set VERDICT_ADMIN_KEY)" });
+        const header = c.req.header("authorization")?.replace(/^Bearer\s+/i, "");
+        if (header !== adminKey)
+            throw new HTTPException(401, { message: "invalid admin key" });
+        await next();
+    });
+    registerAdminKeys(app, keys);
+    registerTakedowns(app, engine, now);
+}
+/* ---------- admin: API keys ---------- */
+function registerAdminKeys(app, keys) {
+    const manager = () => {
+        if (!keys)
+            throw new HTTPException(404, { message: "key management needs a database-backed key store" });
+        return keys;
+    };
+    app.post("/v1/admin/keys", async (c) => {
+        const body = z.object({ tenantId: z.string().min(1), name: z.string().min(1) }).parse(await c.req.json());
+        return c.json(await manager().createKey(body.tenantId, body.name), 201);
+    });
+    app.get("/v1/admin/keys", async (c) => {
+        const tenantId = c.req.query("tenant");
+        if (!tenantId)
+            throw new ValidationError("query param `tenant` is required");
+        return c.json({ data: await manager().listKeys(tenantId) });
+    });
+    app.delete("/v1/admin/keys/:id", async (c) => {
+        if (!(await manager().revokeKey(c.req.param("id"))))
+            throw new NotFoundError(`key ${c.req.param("id")} not found`);
+        return c.body(null, 204);
+    });
+}
+/*
+ * ---------- admin: hub takedowns (docs/design/hub.md H6) ----------
+ * Operators can take any publication down, with a reason that is shown publicly, and put back only what they took down:
+ * an author's own withdrawal is the author's to keep.
+ */
+function registerTakedowns(app, engine, now) {
+    const store = () => {
+        if (!hasPublications(engine.store))
+            throw new HTTPException(404, { message: "this server's store cannot keep publications" });
+        return engine.store;
+    };
+    const find = async (id) => {
+        const p = await store().getPublication(id);
+        if (!p)
+            throw new NotFoundError(`publication ${id} not found`);
+        return p;
+    };
+    app.get("/v1/admin/publications", async (c) => {
+        const q = z.object({ q: z.string().optional(), owner: z.string().optional(), slug: z.string().optional(), limit: z.coerce.number().int().min(1).max(500).default(100) }).parse(c.req.query());
+        return c.json({ data: await store().listPublications({ ...q, includeWithdrawn: true }) });
+    });
+    app.post("/v1/admin/publications/:id/takedown", async (c) => {
+        const { reason } = z.object({ reason: z.string().trim().min(1).max(500) }).parse(await c.req.json());
+        const p = await find(c.req.param("id")), at = new Date(now()).toISOString();
+        const next = { ...p, withdrawnAt: p.withdrawnAt ?? at, takedown: { reason, at } };
+        await store().putPublication(next);
+        return c.json({ publication: next });
+    });
+    app.post("/v1/admin/publications/:id/restore", async (c) => {
+        const p = await find(c.req.param("id"));
+        if (!p.takedown)
+            throw new HTTPException(409, { message: `${p.ref} at ${p.version.id} was not taken down${p.withdrawnAt ? "; its author withdrew it" : ""}` });
+        const { takedown: _takedown, withdrawnAt: _withdrawnAt, ...restored } = p;
+        await store().putPublication(restored);
+        return c.json({ publication: restored });
+    });
+}
+//# sourceMappingURL=admin.js.map

package/dist/routes/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../../src/routes/admin.ts"],"names":[],"mappings":"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"}

package/dist/routes/batches.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { AppOptions, Env } from "../app.js";
+/** Registers batches operations; handler failures propagate to the transport error boundary. */
+export declare function registerBatches(app: Hono<Env>, { engine }: AppOptions): void;

package/dist/routes/batches.js

@@ -0,0 +1,27 @@
+/**
+ * Tenant context flows to every engine/store operation; validation failures use the shared HTTP error mapper.
+ */
+import { Rubric, Subject } from "@verdict-ai/core";
+import { z } from "zod";
+import { present } from "../present.js";
+import { readIdempotencyKey, tenant } from "./shared.js";
+/** Registers batches operations; handler failures propagate to the transport error boundary. */
+export function registerBatches(app, { engine }) {
+    /* ---------- batches (leaderboards) ---------- */
+    app.post("/v1/batches", async (c) => {
+        const raw = z.record(z.string(), z.unknown()).parse(await c.req.json());
+        const idempotencyKey = readIdempotencyKey(c.req.raw);
+        const body = z.object({ rubric: z.union([z.string(), Rubric]), subjects: z.array(Subject).min(1), metadata: z.record(z.string(), z.unknown()).optional(), webhook: z.string().url().optional() }).parse(raw);
+        const opts = { tenantId: tenant(c), metadata: body.metadata, webhook: body.webhook };
+        // why: preserve the submitted body for conflict detection instead of hashing schema defaults.
+        const fingerprintBody = Object.fromEntries(["rubric", "subjects", "metadata", "webhook"].filter(k => k in raw).map(k => [k, raw[k]]));
+        const result = idempotencyKey === undefined
+            ? { ...await engine.evaluateBatch(body.rubric, body.subjects, opts), replayed: false }
+            : await engine.evaluateBatchIdempotent(body.rubric, body.subjects, { ...opts, idempotencyKey, fingerprintBody });
+        const { evaluations, ranking, replayed } = result;
+        if (replayed)
+            c.header("Idempotency-Replayed", "true");
+        return c.json({ ranking, evaluations: evaluations.map((e) => present(e, { ratings: false })) }, replayed ? 200 : 201);
+    });
+}
+//# sourceMappingURL=batches.js.map

package/dist/routes/batches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batches.js","sourceRoot":"","sources":["../../src/routes/batches.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEzD,gGAAgG;AAChG,MAAM,UAAU,eAAe,CAAC,GAAc,EAAE,EAAE,MAAM,EAAc;IACpE,kDAAkD;IAClD,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAClC,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACxE,MAAM,cAAc,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7M,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACrF,8FAA8F;QAC9F,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtI,MAAM,MAAM,GAAG,cAAc,KAAK,SAAS;YACzC,CAAC,CAAC,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE;YACtF,CAAC,CAAC,MAAM,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC,CAAC;QACnH,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QAClD,IAAI,QAAQ;YAAE,CAAC,CAAC,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;QACvD,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxH,CAAC,CAAC,CAAC;AAEL,CAAC"}

package/dist/routes/evaluations.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { AppOptions, Env } from "../app.js";
+/** Registers evaluations operations; handler failures propagate to the transport error boundary. */
+export declare function registerEvaluations(app: Hono<Env>, { engine, allowAsync, background }: AppOptions): void;

package/dist/routes/evaluations.js

@@ -0,0 +1,104 @@
+/**
+ * Tenant context flows to every engine/store operation; validation failures use the shared HTTP error mapper.
+ */
+import { Aggregation, NotFoundError, Rubric, Subject, ValidationError } from "@verdict-ai/core";
+import { z } from "zod";
+import { present } from "../present.js";
+import { readIdempotencyKey, tenant } from "./shared.js";
+// why: the inbox is bounded independently of ordinary listings so pending tasks remain useful without unbounded reads.
+const TASK_INBOX_LIMIT = 500;
+/** Registers evaluations operations; handler failures propagate to the transport error boundary. */
+export function registerEvaluations(app, { engine, allowAsync, background }) {
+    /* ---------- evaluations ---------- */
+    app.post("/v1/evaluations", async (c) => {
+        const parsed = await parseEvaluateBody(c);
+        const { body } = parsed;
+        if (body.async && allowAsync)
+            return respondAsync(c, engine, parsed, background);
+        return respondSync(c, engine, parsed);
+    });
+    app.get("/v1/evaluations", async (c) => {
+        const list = await engine.store.listEvaluations({ tenantId: tenant(c), rubricId: c.req.query("rubric"), status: c.req.query("status"), limit: Number(c.req.query("limit") ?? 50) });
+        return c.json({ data: list.map((e) => present(e, { ratings: false })) });
+    });
+    app.get("/v1/evaluations/:id", async (c) => {
+        const ev = await engine.store.getEvaluation(c.req.param("id"), tenant(c));
+        if (!ev)
+            throw new NotFoundError(`evaluation ${c.req.param("id")} not found`);
+        return c.json(present(ev, { evidence: c.req.query("evidence") === "true" }));
+    });
+    app.post("/v1/evaluations/:id/retry", async (c) => {
+        const ev = await engine.retryEvaluation(c.req.param("id"), tenant(c));
+        return c.json({ id: ev.id, status: "queued", url: `/v1/evaluations/${ev.id}` }, 202);
+    });
+    const ScoreBody = z.object({ criterionId: z.string(), raterId: z.string(), score: z.union([z.number(), z.string()]), rationale: z.string().optional(), confidence: z.number().min(0).max(1).optional() });
+    app.post("/v1/evaluations/:id/scores", async (c) => {
+        const body = ScoreBody.parse(await c.req.json());
+        return c.json(present(await engine.submitScore(c.req.param("id"), body, tenant(c))));
+    });
+    /** Human task inbox: everything waiting on a rater. */
+    app.get("/v1/tasks", async (c) => {
+        const rater = c.req.query("rater");
+        const list = await engine.store.listEvaluations({ tenantId: tenant(c), status: "pending_human", limit: TASK_INBOX_LIMIT });
+        const tasks = list.flatMap((e) => e.pendingTasks.filter((t) => !rater || (t.raterId ? t.raterId === rater : !t.allowedRaters || t.allowedRaters.includes(rater))).map((t) => ({ evaluationId: e.id, rubric: e.rubric.name, subject: e.subject.name, ...t })));
+        return c.json({ data: tasks });
+    });
+    app.post("/v1/evaluations/:id/aggregate", async (c) => {
+        const body = z.object({ aggregation: Aggregation.partial(), persist: z.boolean().default(false) }).parse(await c.req.json());
+        return c.json(present(await engine.reaggregate(c.req.param("id"), body.aggregation, tenant(c), body.persist)));
+    });
+}
+const EvaluateBody = z.object({
+    rubric: z.union([z.string(), Rubric]),
+    subject: Subject.optional(),
+    /** Shorthand: inputs at top level instead of subject.inputs. */
+    inputs: Subject.shape.inputs.optional(),
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    webhook: z.string().url().optional(),
+    async: z.boolean().optional(),
+    /** Include full evidence text in the response. */
+    includeEvidence: z.boolean().optional(),
+});
+async function parseEvaluateBody(c) {
+    const raw = z.record(z.string(), z.unknown()).parse(await c.req.json());
+    const body = EvaluateBody.parse(raw);
+    const idempotencyKey = readIdempotencyKey(c.req.raw);
+    // why: transport-only flags do not change evaluation identity; hash only scoring inputs and delivery metadata.
+    const fingerprintBody = Object.fromEntries(["rubric", "subject", "inputs", "name", "metadata", "webhook"].filter(k => k in raw).map(k => [k, raw[k]]));
+    const subject = body.subject ?? { name: body.name, inputs: body.inputs ?? [] };
+    if (!subject.inputs?.length)
+        throw new ValidationError("provide `subject.inputs` or `inputs`");
+    const req = { rubric: body.rubric, subject, tenantId: tenant(c), metadata: body.metadata, webhook: body.webhook };
+    return { body, req, idempotencyKey, fingerprintBody };
+}
+async function respondAsync(c, engine, { req, idempotencyKey, fingerprintBody }, background) {
+    // why: durable queues own retries; the background fallback is for deployments without a queue binding.
+    if (engine.queue) {
+        const result = idempotencyKey === undefined
+            ? { evaluation: await engine.enqueueEvaluation(req), replayed: false }
+            : await engine.enqueueEvaluationIdempotent({ ...req, idempotencyKey, fingerprintBody });
+        // why: a replay returns the existing resource with 200 instead of claiming a new job was accepted.
+        if (result.replayed)
+            c.header("Idempotency-Replayed", "true");
+        return c.json({ id: result.evaluation.id, status: result.evaluation.status, url: `/v1/evaluations/${result.evaluation.id}` }, result.replayed ? 200 : 202);
+    }
+    {
+        const result = await engine.evaluateBackground({ ...req, idempotencyKey, fingerprintBody }, background ?? (work => { void work.catch(error => console.error("Background evaluation failed", error)); }));
+        if (result.replayed)
+            c.header("Idempotency-Replayed", "true");
+        return c.json({ id: result.evaluation.id, status: result.replayed ? result.evaluation.status : "queued", url: `/v1/evaluations/${result.evaluation.id}` }, result.replayed ? 200 : 202);
+    }
+}
+async function respondSync(c, engine, { req, idempotencyKey, fingerprintBody, body }) {
+    const includeEvidence = body.includeEvidence;
+    if (idempotencyKey !== undefined) {
+        const { evaluation, replayed } = await engine.evaluateIdempotent({ ...req, idempotencyKey, fingerprintBody });
+        if (replayed)
+            c.header("Idempotency-Replayed", "true");
+        return c.json(present(evaluation, { evidence: includeEvidence }), replayed ? 200 : evaluation.status === "failed" ? 422 : 201);
+    }
+    const ev = await engine.evaluate(req);
+    return c.json(present(ev, { evidence: includeEvidence }), ev.status === "failed" ? 422 : 201);
+}
+//# sourceMappingURL=evaluations.js.map

package/dist/routes/evaluations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluations.js","sourceRoot":"","sources":["../../src/routes/evaluations.ts"],"names":[],"mappings":"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"}

package/dist/routes/hub.d.ts

@@ -0,0 +1,12 @@
+import { Hono } from "hono";
+import type { AppOptions, Env } from "../app.js";
+/** Paths that answer without an API key. */
+export declare const PUBLIC_HUB_PATHS: Set<string>;
+/** The tenant of a GitHub account. Numeric ids survive renamed logins. */
+export declare const githubTenant: (githubId: number) => string;
+export declare function registerHub(app: Hono<Env>, { engine, keys, github, now, limits, clientKey, signIn }: AppOptions): void;
+/**
+ * Who a tenant publishes as. With GitHub sign-in configured, only signed-in GitHub accounts publish, under their
+ * login; without it (a self-hosted team server), a tenant publishes under its own id, an open server as "local".
+ */
+export declare function publisherFor(opts: Pick<AppOptions, "engine" | "github">): (tenantId: string | undefined) => Promise<string | undefined>;

package/dist/routes/hub.js

@@ -0,0 +1,66 @@
+/**
+ * Hub sign-in (docs/design/hub.md H2). `GET /v1/hub/config` and `POST /v1/hub/login` are public: the CLI learns the
+ * GitHub client id, runs the device flow, and trades the GitHub token for a hub API key bound to the GitHub account.
+ * `GET /v1/hub/me` and `DELETE /v1/hub/keys/:id` are authenticated.
+ */
+import { hasPublishers } from "@verdict-ai/core";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { verifyGithubToken } from "../github.js";
+import { defaultClientKey, enforce } from "../rate-limit.js";
+import { tenant } from "./shared.js";
+/** Paths that answer without an API key. */
+export const PUBLIC_HUB_PATHS = new Set(["/v1/hub/config", "/v1/hub/login"]);
+/** The tenant of a GitHub account. Numeric ids survive renamed logins. */
+export const githubTenant = (githubId) => `gh:${githubId}`;
+export function registerHub(app, { engine, keys, github, now = () => Date.now(), limits, clientKey = defaultClientKey, signIn }) {
+    const publishers = () => {
+        if (!hasPublishers(engine.store))
+            throw new HTTPException(501, { message: "this server's store cannot keep publishers" });
+        return engine.store;
+    };
+    app.get("/v1/hub/config", (c) => c.json({ github: github ? { clientId: github.clientId } : null, publishing: github ? "github" : "tenant", ...(signIn ? { signIn } : {}) }));
+    app.post("/v1/hub/login", async (c) => {
+        if (!github)
+            throw new HTTPException(501, { message: "GitHub sign-in is not configured on this server (GITHUB_CLIENT_ID)" });
+        if (!keys)
+            throw new HTTPException(501, { message: "this server cannot issue API keys (needs a database store)" });
+        // Each sign-in asks GitHub and mints a key: limit it per client before doing either.
+        await enforce(limits?.login, clientKey(c), "sign-in");
+        const { githubToken } = z.object({ githubToken: z.string().min(1).max(512) }).parse(await c.req.json());
+        const account = await verifyGithubToken(githubToken, github);
+        const tenantId = githubTenant(account.id), at = new Date(now()).toISOString();
+        const existing = await publishers().getPublisher(tenantId);
+        await publishers().putPublisher({ tenantId, githubId: account.id, login: account.login, createdAt: existing?.createdAt ?? at, updatedAt: at });
+        const key = await keys.createKey(tenantId, `hub sign-in (${account.login})`);
+        // The GitHub token is not stored anywhere; the hub key is shown once, here.
+        return c.json({ apiKey: key.key, keyId: key.id, handle: account.login, tenantId }, 201);
+    });
+    app.get("/v1/hub/me", async (c) => {
+        const tenantId = tenant(c);
+        const publisher = tenantId && hasPublishers(engine.store) ? await engine.store.getPublisher(tenantId) : undefined;
+        return c.json({ tenantId: tenantId ?? null, handle: publisher?.login ?? (github ? null : tenantId ?? "local"), github: publisher ? { id: publisher.githubId, login: publisher.login } : null });
+    });
+    app.delete("/v1/hub/keys/:id", async (c) => {
+        if (!keys)
+            throw new HTTPException(501, { message: "this server cannot manage API keys" });
+        const tenantId = tenant(c);
+        if (!tenantId || !(await keys.revokeKey(c.req.param("id"), tenantId)))
+            throw new HTTPException(404, { message: "no such key for this account" });
+        return c.body(null, 204);
+    });
+}
+/**
+ * Who a tenant publishes as. With GitHub sign-in configured, only signed-in GitHub accounts publish, under their
+ * login; without it (a self-hosted team server), a tenant publishes under its own id, an open server as "local".
+ */
+export function publisherFor(opts) {
+    return async (tenantId) => {
+        if (!opts.github)
+            return tenantId ?? "local";
+        if (!tenantId || !hasPublishers(opts.engine.store))
+            return undefined;
+        return (await opts.engine.store.getPublisher(tenantId))?.login;
+    };
+}
+//# sourceMappingURL=hub.js.map

package/dist/routes/hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.js","sourceRoot":"","sources":["../../src/routes/hub.ts"],"names":[],"mappings":"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"}

package/dist/routes/project-versions.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { AppOptions, Env } from "../app.js";
+/** Registers version routes. */
+export declare function registerProjectVersions(app: Hono<Env>, options: AppOptions): void;

package/dist/routes/project-versions.js

@@ -0,0 +1,56 @@
+/**
+ * Immutable rubric versions kept in a project (docs/design/control-plane.md §4). A version is stored under the name
+ * services ask for; the server freezes the uploaded rubric again and refuses an id that does not match its content.
+ */
+import { CONTROL_LIST_LIMIT, CONTROL_VERSION_BYTES, controlName, NotFoundError, projectVersion, VersionUpload } from "@verdict-ai/core";
+import { z } from "zod";
+import { ApiError, bare, controlContext, projectNotFound, readJson } from "./shared.js";
+/** A version as lists show it: everything but the rubric document. */
+function listed(v) {
+    const { rubric: _rubric, ...rest } = bare(v);
+    return rest;
+}
+/** Registers version routes. */
+export function registerProjectVersions(app, options) {
+    const { store, scope, allow, project, now } = controlContext(options);
+    const base = "/v1/projects/:project/rubrics";
+    const missing = (name, id, projectName) => new NotFoundError(`version ${id} of ${name} not found in project ${projectName}`);
+    app.post(`${base}/:name/versions`, async (c) => {
+        const s = scope(c), name = c.req.param("name");
+        await allow(c, "version.put", { project: s.project, name });
+        const upload = VersionUpload.parse(await readJson(c.req.raw, CONTROL_VERSION_BYTES));
+        const result = await store().putVersion(await projectVersion(upload, s, controlName(name, "rubric"), now));
+        if (result === "no_project")
+            throw projectNotFound(s.project);
+        return c.json({ version: bare(result.version), created: result.created }, result.created ? 201 : 200);
+    });
+    app.get(base, async (c) => {
+        await allow(c, "version.read", { project: c.req.param("project") });
+        return c.json({ data: await store().listRubricNames(await project(c)) });
+    });
+    app.get(`${base}/:name/versions`, async (c) => {
+        const name = c.req.param("name");
+        await allow(c, "version.read", { project: c.req.param("project"), name });
+        const { limit } = z.object({ limit: z.coerce.number().int().min(1).max(CONTROL_LIST_LIMIT).default(CONTROL_LIST_LIMIT) }).parse(c.req.query());
+        return c.json({ data: (await store().listVersions(await project(c), { name, limit })).map(listed) });
+    });
+    app.get(`${base}/:name/versions/:id`, async (c) => {
+        const s = scope(c), name = c.req.param("name"), id = c.req.param("id");
+        await allow(c, "version.read", { project: s.project, name, versionId: id });
+        const version = await store().getVersion(s, name, id);
+        if (!version)
+            throw missing(name, id, s.project);
+        return c.json(bare(version));
+    });
+    app.delete(`${base}/:name/versions/:id`, async (c) => {
+        const s = scope(c), name = c.req.param("name"), id = c.req.param("id");
+        await allow(c, "version.delete", { project: s.project, name, versionId: id });
+        const result = await store().deleteVersion(s, name, id);
+        if (result === "not_found")
+            throw missing(name, id, s.project);
+        if (result === "in_use")
+            throw new ApiError(409, "in_use", `an environment points at ${id}; promote another version of ${name} or remove the pointer first`);
+        return c.body(null, 204);
+    });
+}
+//# sourceMappingURL=project-versions.js.map

package/dist/routes/project-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-versions.js","sourceRoot":"","sources":["../../src/routes/project-versions.ts"],"names":[],"mappings":"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"}

package/dist/routes/projects.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { AppOptions, Env } from "../app.js";
+/** Registers project and environment routes. */
+export declare function registerProjects(app: Hono<Env>, options: AppOptions): void;

package/dist/routes/projects.js

@@ -0,0 +1,91 @@
+/**
+ * Projects and environments of the control plane (docs/design/control-plane.md §3, §5.3). Authenticated and
+ * tenant-scoped; every handler asks `allow` before it touches the store.
+ */
+import { ConfirmRequest, fingerprint, NameRequest, NotFoundError, ValidationError } from "@verdict-ai/core";
+import { HTTPException } from "hono/http-exception";
+import { ApiError, bare, controlContext, projectNotFound, readJson, tenant } from "./shared.js";
+/** Deleting takes the name twice: once in the URL, once in the body. */
+async function confirmed(req, name, what) {
+    const { confirm } = ConfirmRequest.parse(await readJson(req));
+    if (confirm !== name)
+        throw new ValidationError(`to delete ${what} ${name}, send { "confirm": "${name}" }`);
+}
+/** The document a pointer names. A pointed-at version cannot be deleted, so a miss means the pointer just moved. */
+async function rubricOf(store, scope, pointer) {
+    const version = await store.getVersion(scope, pointer.name, pointer.versionId);
+    if (!version)
+        throw new HTTPException(503, { message: `${pointer.name} changed while it was being read; ask again` });
+    return version.rubric;
+}
+/** Registers project and environment routes. */
+export function registerProjects(app, options) {
+    const { store, allow, at } = controlContext(options);
+    app.post("/v1/projects", async (c) => {
+        const { name } = NameRequest.parse(await readJson(c.req.raw));
+        await allow(c, "project.create", { project: name });
+        const tenantId = tenant(c), project = { ...(tenantId === undefined ? {} : { tenantId }), name, createdAt: at() };
+        if (!(await store().createProject(project)))
+            throw new ApiError(409, "already_exists", `project ${name} already exists`);
+        return c.json(bare(project), 201);
+    });
+    app.get("/v1/projects", async (c) => {
+        await allow(c, "project.read");
+        return c.json({ data: (await store().listProjects(tenant(c))).map(bare) });
+    });
+    app.delete("/v1/projects/:project", async (c) => {
+        const name = c.req.param("project");
+        await allow(c, "project.delete", { project: name });
+        await confirmed(c.req.raw, name, "project");
+        if (!(await store().deleteProject(tenant(c), name)))
+            throw projectNotFound(name);
+        return c.body(null, 204);
+    });
+    registerEnvironments(app, options);
+}
+function registerEnvironments(app, options) {
+    const { store, scope, allow, project, at } = controlContext(options);
+    app.post("/v1/projects/:project/environments", async (c) => {
+        const { name } = NameRequest.parse(await readJson(c.req.raw));
+        const s = scope(c);
+        await allow(c, "environment.create", { project: s.project, environment: name });
+        const environment = { ...s, name, createdAt: at() };
+        const result = await store().createEnvironment(environment);
+        if (result === "no_project")
+            throw projectNotFound(s.project);
+        if (result === "exists")
+            throw new ApiError(409, "already_exists", `environment ${name} already exists in project ${s.project}`);
+        return c.json(bare(environment), 201);
+    });
+    app.get("/v1/projects/:project/environments", async (c) => {
+        await allow(c, "environment.read", { project: c.req.param("project") });
+        return c.json({ data: (await store().listEnvironments(await project(c))).map(bare) });
+    });
+    // What a service polls: `?include=rubrics` returns the documents too, so one answer holds everything an environment
+    // runs. Versions never change, so the pointers alone identify the answer: an unchanged environment answers 304.
+    app.get("/v1/projects/:project/environments/:environment", async (c) => {
+        const s = scope(c), name = c.req.param("environment"), withRubrics = c.req.query("include") === "rubrics";
+        await allow(c, "environment.read", { project: s.project, environment: name });
+        const environment = await store().getEnvironment(s, name);
+        if (!environment)
+            throw new NotFoundError(`environment ${name} not found in project ${s.project}`);
+        const pointers = (await store().listPointers(s, name)).map((p) => ({ name: p.name, versionId: p.versionId, updatedAt: p.updatedAt }));
+        const etag = `"${await fingerprint([environment.createdAt, withRubrics, pointers.map((p) => [p.name, p.versionId])])}"`;
+        c.header("ETag", etag);
+        c.header("Cache-Control", "private, no-cache");
+        if (c.req.header("if-none-match") === etag)
+            return c.body(null, 304);
+        if (!withRubrics)
+            return c.json({ ...bare(environment), pointers });
+        return c.json({ ...bare(environment), pointers: await Promise.all(pointers.map(async (p) => ({ ...p, rubric: await rubricOf(store(), s, p) }))) });
+    });
+    app.delete("/v1/projects/:project/environments/:environment", async (c) => {
+        const s = scope(c), name = c.req.param("environment");
+        await allow(c, "environment.delete", { project: s.project, environment: name });
+        await confirmed(c.req.raw, name, "environment");
+        if (!(await store().deleteEnvironment(s, name)))
+            throw new NotFoundError(`environment ${name} not found in project ${s.project}`);
+        return c.body(null, 204);
+    });
+}
+//# sourceMappingURL=projects.js.map