@kindgi/api 0.1.4-rc.1 → 0.1.4-rc.3

package/src/routes/gate-policies.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Context, Hono } from 'hono';
+
+import { ref } from '@kindgi/authz';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { GatePolicyBinding, GatePolicyError } from '../gate-policy-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+import { scopeFromQuery } from './agent-releases.js';
+import { parseGatePolicySpec } from './gate-policy-spec.js';
+import { serializeGatePolicy } from './gate-policy-wire.js';
+import { parseLiveScopeBody } from './live-scope-wire.js';
+import { clampLimit } from './pagination.js';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+
+/**
+ * Gate policies (evals step 4b): what a promotion of an agent must show
+ * before a version goes live for a scope. The same registry shape as
+ * retention policies:
+ *   GET  /                                      each policy's latest active version (?agentId=, scope)
+ *   GET  /:policyId                             its latest active version
+ *   GET  /:policyId/versions[/:version]         every version, or one
+ *   POST /                                      publish {id, version, agentId, scope, spec, description?}
+ *   POST /:policyId/versions/:version/unregister|reinstate
+ *
+ * Writes need `admin` on the tenant: whoever may promote mustn't be able
+ * to loosen the gate on their own promotion.
+ */
+export function gatePoliciesRouter(
+  binding: GatePolicyBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  if (authorizer !== undefined) {
+    r.use('*', async (c, next) => {
+      if (c.req.method !== 'POST') return next();
+      const tenantId = c.get('tenantId') as unknown as string;
+      return authorizer.authorize('admin', () => ref('tenant', tenantId))(c, next);
+    });
+  }
+
+  r.get('/', async (c) => {
+    const requestId = c.get('requestId');
+    const scope = scopeFromQuery((n) => c.req.query(n), c.req.queries('segment') ?? []);
+    if (scope.kind === 'err') return badInput(c, requestId, scope.message);
+    const agentId = c.req.query('agentId');
+    const cursor = c.req.query('cursor');
+    const page = await binding.list({
+      tenantId: c.get('tenantId') as TenantId,
+      limit: clampLimit(c.req.query('limit')),
+      ...(agentId !== undefined && agentId.length > 0 && { agentId }),
+      ...(scope.scope !== undefined && { scope: scope.scope }),
+      ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor as Cursor }),
+    });
+    return c.json({
+      data: page.data.map(serializeGatePolicy),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  r.get('/:policyId', async (c) => {
+    const found = await binding.get({
+      tenantId: c.get('tenantId') as TenantId,
+      id: c.req.param('policyId'),
+    });
+    if (found === null) return notFound(c, c.req.param('policyId'));
+    return c.json(serializeGatePolicy(found));
+  });
+
+  r.get('/:policyId/versions', async (c) => {
+    const versions = await binding.listVersions({
+      tenantId: c.get('tenantId') as TenantId,
+      id: c.req.param('policyId'),
+    });
+    if (versions.length === 0) return notFound(c, c.req.param('policyId'));
+    return c.json({ data: versions.map(serializeGatePolicy), hasMore: false });
+  });
+
+  r.get('/:policyId/versions/:version', async (c) => {
+    const found = await binding.getVersion({
+      tenantId: c.get('tenantId') as TenantId,
+      id: c.req.param('policyId'),
+      version: c.req.param('version'),
+    });
+    if (found === null) {
+      return notFound(c, c.req.param('policyId'), c.req.param('version'));
+    }
+    return c.json(serializeGatePolicy(found));
+  });
+
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return badInput(c, requestId, 'Request body must be a JSON object');
+    }
+    const parsed = parsePublishBody(body);
+    if (parsed.kind === 'err') {
+      c.status(statusFor('validation-failed') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'validation-failed',
+            message: `The gate policy isn't valid: ${parsed.issues.map((i) => `${i.path}: ${i.message}`).join('; ')}`,
+            issues: parsed.issues,
+          },
+          requestId,
+        ),
+      );
+    }
+    const outcome = await binding.publish({
+      tenantId: c.get('tenantId') as TenantId,
+      ...parsed.value,
+    });
+    if (outcome.kind === 'err') return failed(c, requestId, outcome.error);
+    c.status(201);
+    return c.json(serializeGatePolicy(outcome.value));
+  });
+
+  for (const action of ['unregister', 'reinstate'] as const) {
+    r.post(`/:policyId/versions/:version/${action}`, async (c) => {
+      const outcome = await binding[action]({
+        tenantId: c.get('tenantId') as TenantId,
+        id: c.req.param('policyId'),
+        version: c.req.param('version'),
+      });
+      if (outcome.kind === 'err') return failed(c, c.get('requestId'), outcome.error);
+      return c.json(serializeGatePolicy(outcome.value));
+    });
+  }
+
+  return r;
+}
+
+type Ctx = Context<AppEnv>;
+
+function badInput(c: Ctx, requestId: string, message: string) {
+  c.status(statusFor('bad-input') as never);
+  return c.json(toWireError({ code: 'bad-input', message }, requestId));
+}
+
+function notFound(c: Ctx, policyId: string, version?: string) {
+  c.status(statusFor('gate-policy-not-found') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'gate-policy-not-found',
+        message:
+          version === undefined
+            ? `No active gate policy "${policyId}"`
+            : `Gate policy "${policyId}" has no version ${version}`,
+        policyId,
+      },
+      c.get('requestId'),
+    ),
+  );
+}
+
+function failed(c: Ctx, requestId: string, error: GatePolicyError) {
+  c.status(statusFor(error.code) as never);
+  return c.json(toWireError({ ...error }, requestId));
+}
+
+type Issue = { readonly path: string; readonly message: string };
+
+function parsePublishBody(body: unknown):
+  | {
+      kind: 'ok';
+      value: Omit<Parameters<GatePolicyBinding['publish']>[0], 'tenantId'>;
+    }
+  | { kind: 'err'; issues: readonly Issue[] } {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { kind: 'err', issues: [{ path: '', message: 'the body must be a JSON object' }] };
+  }
+  const b = body as Record<string, unknown>;
+  const issues: Issue[] = [];
+  for (const key of Object.keys(b)) {
+    if (!['id', 'version', 'agentId', 'scope', 'spec', 'description'].includes(key)) {
+      issues.push({ path: `/${key}`, message: `\`${key}\` isn't a gate policy field` });
+    }
+  }
+  if (typeof b.id !== 'string' || !ID_RE.test(b.id)) {
+    issues.push({
+      path: '/id',
+      message:
+        '`id` must be lowercase letters, digits, `.`, `_` or `-` (e.g. "acme.drafting-prod")',
+    });
+  }
+  if (typeof b.version !== 'string' || !SEMVER_RE.test(b.version)) {
+    issues.push({ path: '/version', message: '`version` must be a semver version (e.g. "1.0.0")' });
+  }
+  if (typeof b.agentId !== 'string' || b.agentId === '') {
+    issues.push({ path: '/agentId', message: '`agentId` is required: the agent the policy gates' });
+  }
+  const scope = parseLiveScopeBody(b.scope);
+  if (scope.kind === 'err') issues.push({ path: '/scope', message: scope.message });
+  const spec = parseGatePolicySpec(b.spec);
+  if (spec.kind === 'err') issues.push(...spec.issues);
+  if (b.description !== undefined && (typeof b.description !== 'string' || b.description === '')) {
+    issues.push({ path: '/description', message: '`description` must be a non-empty string' });
+  }
+  if (issues.length > 0 || scope.kind === 'err' || spec.kind === 'err') {
+    return { kind: 'err', issues };
+  }
+  return {
+    kind: 'ok',
+    value: {
+      id: b.id as string,
+      version: b.version as string,
+      agentId: b.agentId as string,
+      scope: scope.scope,
+      spec: spec.spec,
+      ...(typeof b.description === 'string' && { description: b.description }),
+    },
+  };
+}

package/src/routes/gate-policy-spec.ts

@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { REVIEWER_ROLE_RANK, type ReviewerRole } from '@kindgi/authz';
+
+import { GATE_METRICS, type GateMetricSpec, type GatePolicySpec } from '../gate-policy-binding.js';
+
+/**
+ * A gate policy's `spec`, checked strictly: an unknown key is an issue, so
+ * a typo can't leave a check silently off.
+ */
+
+export interface SpecIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+type Raw = Readonly<Record<string, unknown>>;
+
+const REVIEWER_ROLES = Object.keys(REVIEWER_ROLE_RANK) as readonly ReviewerRole[];
+
+const isObject = (v: unknown): v is Raw => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Keys the policy may not use yet, with why. */
+const LATER: Readonly<Record<string, string>> = {
+  '/spec/approvals/count': 'one reviewer decides a promotion today; leave `count` out',
+  '/spec/approvals/forRollback': "rollbacks aren't gated yet; leave `forRollback` out",
+};
+
+function unknownKeys(raw: Raw, allowed: readonly string[], at: string, issues: SpecIssue[]) {
+  for (const key of Object.keys(raw)) {
+    if (allowed.includes(key)) continue;
+    const path = `${at}/${key}`;
+    issues.push({
+      path,
+      message:
+        LATER[path] ??
+        `\`${key}\` isn't a gate policy setting here (expected: ${allowed.join(', ')})`,
+    });
+  }
+}
+
+/** A number in [min, max], when present. */
+function num(
+  raw: Raw,
+  key: string,
+  at: string,
+  issues: SpecIssue[],
+  opts: { min: number; max?: number; integer?: boolean; positive?: boolean },
+): number | undefined {
+  const v = raw[key];
+  if (v === undefined) return undefined;
+  const ok =
+    typeof v === 'number' &&
+    Number.isFinite(v) &&
+    v >= opts.min &&
+    (opts.max === undefined || v <= opts.max) &&
+    (opts.integer !== true || Number.isInteger(v)) &&
+    (opts.positive !== true || v > 0);
+  if (!ok) {
+    const range = opts.max === undefined ? `at least ${opts.min}` : `${opts.min} to ${opts.max}`;
+    issues.push({
+      path: `${at}/${key}`,
+      message: `\`${key}\` must be ${opts.integer === true ? 'a whole number' : 'a number'}, ${opts.positive === true ? 'above 0' : range}`,
+    });
+    return undefined;
+  }
+  return v as number;
+}
+
+function bool(raw: Raw, key: string, at: string, issues: SpecIssue[]): boolean | undefined {
+  const v = raw[key];
+  if (v === undefined) return undefined;
+  if (typeof v !== 'boolean') {
+    issues.push({ path: `${at}/${key}`, message: `\`${key}\` must be true or false` });
+    return undefined;
+  }
+  return v;
+}
+
+function block(raw: Raw, key: string, issues: SpecIssue[]): Raw | undefined {
+  const v = raw[key];
+  if (v === undefined) return undefined;
+  if (!isObject(v)) {
+    issues.push({ path: `/spec/${key}`, message: `\`${key}\` must be an object` });
+    return undefined;
+  }
+  return v;
+}
+
+export function parseGatePolicySpec(
+  raw: unknown,
+): { kind: 'ok'; spec: GatePolicySpec } | { kind: 'err'; issues: readonly SpecIssue[] } {
+  if (!isObject(raw)) {
+    return { kind: 'err', issues: [{ path: '/spec', message: '`spec` must be an object' }] };
+  }
+  const issues: SpecIssue[] = [];
+  unknownKeys(
+    raw,
+    ['comparison', 'evidence', 'metrics', 'replay', 'approvals', 'onlyRestrictedClasses'],
+    '/spec',
+    issues,
+  );
+  const spec: {
+    -readonly [K in keyof GatePolicySpec]: GatePolicySpec[K];
+  } = {};
+
+  const comparison = block(raw, 'comparison', issues);
+  if (comparison !== undefined) {
+    const at = '/spec/comparison';
+    unknownKeys(comparison, ['maxAgeHours', 'suite'], at, issues);
+    const maxAgeHours = num(comparison, 'maxAgeHours', at, issues, { min: 0, positive: true });
+    let suite: { id: string; version?: string } | undefined;
+    if (comparison.suite !== undefined) {
+      const s = comparison.suite;
+      if (!isObject(s) || typeof s.id !== 'string' || s.id === '') {
+        issues.push({ path: `${at}/suite`, message: '`suite` must be `{ id, version? }`' });
+      } else {
+        unknownKeys(s, ['id', 'version'], `${at}/suite`, issues);
+        if (s.version !== undefined && (typeof s.version !== 'string' || s.version === '')) {
+          issues.push({ path: `${at}/suite/version`, message: '`version` must be a version' });
+        }
+        suite = { id: s.id, ...(typeof s.version === 'string' && { version: s.version }) };
+      }
+    }
+    spec.comparison = {
+      ...(maxAgeHours !== undefined && { maxAgeHours }),
+      ...(suite !== undefined && { suite }),
+    };
+  }
+
+  const evidence = block(raw, 'evidence', issues);
+  if (evidence !== undefined) {
+    const at = '/spec/evidence';
+    unknownKeys(evidence, ['minCases', 'minWeight'], at, issues);
+    const minCases = num(evidence, 'minCases', at, issues, { min: 0, integer: true });
+    const minWeight = num(evidence, 'minWeight', at, issues, { min: 0 });
+    spec.evidence = {
+      ...(minCases !== undefined && { minCases }),
+      ...(minWeight !== undefined && { minWeight }),
+    };
+  }
+
+  if (raw.metrics !== undefined) {
+    if (!Array.isArray(raw.metrics)) {
+      issues.push({ path: '/spec/metrics', message: '`metrics` must be a list' });
+    } else {
+      const metrics: GateMetricSpec[] = [];
+      const seen = new Set<string>();
+      raw.metrics.forEach((m: unknown, i: number) => {
+        const at = `/spec/metrics/${i}`;
+        const before = issues.length;
+        if (!isObject(m)) {
+          issues.push({ path: at, message: 'each metric must be an object' });
+          return;
+        }
+        unknownKeys(m, ['name', 'k', 'minCandidate', 'maxDrop'], at, issues);
+        const name = m.name;
+        if (typeof name !== 'string' || !(GATE_METRICS as readonly string[]).includes(name)) {
+          issues.push({
+            path: `${at}/name`,
+            message: `\`name\` must be one of: ${GATE_METRICS.join(', ')}`,
+          });
+          return;
+        }
+        if (seen.has(name)) {
+          issues.push({ path: `${at}/name`, message: `\`${name}\` is gated twice` });
+          return;
+        }
+        seen.add(name);
+        if (m.k !== undefined && name !== 'weightedPrecisionAtK') {
+          issues.push({ path: `${at}/k`, message: '`k` applies to `weightedPrecisionAtK` only' });
+        }
+        const k = num(m, 'k', at, issues, { min: 1, max: 100, integer: true });
+        const minCandidate = num(m, 'minCandidate', at, issues, { min: 0, max: 1 });
+        const maxDrop = num(m, 'maxDrop', at, issues, { min: 0, max: 1 });
+        if (minCandidate === undefined && maxDrop === undefined && issues.length === before) {
+          issues.push({
+            path: at,
+            message: `\`${name}\` needs \`minCandidate\`, \`maxDrop\` or both: what it must reach`,
+          });
+        }
+        metrics.push({
+          name: name as GateMetricSpec['name'],
+          ...(k !== undefined && { k }),
+          ...(minCandidate !== undefined && { minCandidate }),
+          ...(maxDrop !== undefined && { maxDrop }),
+        });
+      });
+      spec.metrics = metrics;
+    }
+  }
+
+  const replay = block(raw, 'replay', issues);
+  if (replay !== undefined) {
+    const at = '/spec/replay';
+    const knobs = ['maxDiverged', 'maxErrors', 'maxRefusedWrites', 'maxStopped'] as const;
+    unknownKeys(replay, knobs, at, issues);
+    const out: { -readonly [K in (typeof knobs)[number]]?: number } = {};
+    for (const knob of knobs) {
+      const v = num(replay, knob, at, issues, { min: 0, integer: true });
+      if (v !== undefined) out[knob] = v;
+    }
+    spec.replay = out;
+  }
+
+  const approvals = block(raw, 'approvals', issues);
+  if (approvals !== undefined) {
+    const at = '/spec/approvals';
+    unknownKeys(approvals, ['role', 'separateApprover'], at, issues);
+    const role = approvals.role;
+    if (role !== undefined && !(REVIEWER_ROLES as readonly unknown[]).includes(role)) {
+      issues.push({
+        path: `${at}/role`,
+        message: `\`role\` must be one of: ${REVIEWER_ROLES.join(', ')}`,
+      });
+    }
+    const separateApprover = bool(approvals, 'separateApprover', at, issues);
+    spec.approvals = {
+      ...(typeof role === 'string' && { role: role as ReviewerRole }),
+      ...(separateApprover !== undefined && { separateApprover }),
+    };
+  }
+
+  const onlyRestricted = bool(raw, 'onlyRestrictedClasses', '/spec', issues);
+  if (onlyRestricted !== undefined) spec.onlyRestrictedClasses = onlyRestricted;
+
+  return issues.length > 0 ? { kind: 'err', issues } : { kind: 'ok', spec };
+}

package/src/routes/gate-policy-wire.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { GatePolicy } from '../gate-policy-binding.js';
+import { liveScopeToWire } from './live-scope-wire.js';
+
+export function serializeGatePolicy(p: GatePolicy): Record<string, unknown> {
+  return {
+    id: p.id,
+    version: p.version,
+    agentId: p.agentId,
+    scope: liveScopeToWire(p.scope),
+    spec: p.spec,
+    ...(p.description !== undefined && { description: p.description }),
+    createdAt: p.createdAt as unknown as string,
+    ...(p.unregisteredAt !== undefined && {
+      unregisteredAt: p.unregisteredAt as unknown as string,
+    }),
+  };
+}

package/src/routes/hierarchy-errors.ts

@@ -58,3 +58,17 @@ export function projectDefaultAlreadyExistsError() {
     message: 'The tenant already has a Default project',
   } as const;
 }
+
+/**
+ * `501 authz-membership-unsupported`: authorization is enforced, but the
+ * tenant-hierarchy binding can't change a membership together with its
+ * authorization tuple (it has no `method`). Nothing is changed: removing
+ * the row alone would leave the user's permission in place.
+ */
+export function membershipNotKeptInStepError(method: string) {
+  return {
+    code: 'authz-membership-unsupported',
+    message: `This runtime can't keep permissions in step with a membership change (its tenant-hierarchy binding has no ${method}), so nothing was changed.`,
+    method,
+  } as const;
+}

package/src/routes/judged-suites.ts

@@ -252,12 +252,16 @@ async function summarize(
   let no = 0;
   let yesWeight = 0;
   let totalWeight = 0;
+  // What judges a class was restricted to asserted, as it was when each judgment was recorded.
+  const restricted = { yesWeight: 0, totalWeight: 0 };
   for (const j of judgments) {
     const w = await weightOf(j.judgeClassId);
     totalWeight += w;
+    if (j.restricted === true) restricted.totalWeight += w;
     if (j.verdict === 'yes') {
       yes += 1;
       yesWeight += w;
+      if (j.restricted === true) restricted.yesWeight += w;
     } else {
       no += 1;
     }
@@ -271,6 +275,7 @@ async function summarize(
     no,
     yesWeight,
     totalWeight,
+    restricted,
     reasons: judgments.flatMap((j) =>
       j.reason !== undefined ? [{ verdict: j.verdict, reason: j.reason }] : [],
     ),