@kindgi/api 0.1.4-rc.0 → 0.1.4-rc.2

package/src/routes/guardrails.ts

@@ -10,6 +10,7 @@ import type { Cursor, GuardrailId, ProjectId, TenantId, UserId } from '@kindgi/t
 import { statusFor, toWireError } from '../errors.js';
 import type { GuardrailRegistryBinding } from '../guardrail-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
+import { refuseWritesWhenReadOnly } from '../registry-read-only.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
@@ -47,6 +48,12 @@ export function guardrailsRouter(
   onWrite?: GuardrailWriteHook,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  // A read-only registry (under `kindgi dev`, the pack's files) refuses
+  // every write before anything else runs.
+  r.use(
+    '*',
+    refuseWritesWhenReadOnly(() => binding.readOnly),
+  );
 
   // Authorization (PEP) — mirrors agents. Cascade via `guardrail#parent@project`
   // written in-tx by register; direct check via `ref('guardrail', id)`.

package/src/routes/hierarchy-errors.ts

@@ -42,6 +42,15 @@ export function orgDeleteSlugConflictError(slugs: readonly string[]) {
   } as const;
 }
 
+/**
+ * `404 org-not-found`: the org a project or team would be in isn't the
+ * tenant's (it never existed, or it was deleted). The code and message
+ * `GET /v1/orgs/{id}` answers (T220).
+ */
+export function orgNotFoundError(orgId: string) {
+  return { code: 'org-not-found', message: `No org with id "${orgId}"`, orgId } as const;
+}
+
 /** `409 project-default-already-exists`: the tenant has a Default project. */
 export function projectDefaultAlreadyExistsError() {
   return {
@@ -49,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 }] : [],
     ),

package/src/routes/judgments.ts

@@ -4,7 +4,7 @@
 import { type Context, Hono } from 'hono';
 
 import type { ConversationBinding } from '@kindgi/agents';
-import { ref } from '@kindgi/authz';
+import { REVIEWER_ROLE_RANK, type ReviewerRole, ref } from '@kindgi/authz';
 import type { RunBinding } from '@kindgi/runtime';
 import type { Cursor, ProjectId, RunId, TenantId } from '@kindgi/types';
 
@@ -12,6 +12,7 @@ import { statusFor, toWireError } from '../errors.js';
 import type { FlowRegistryBinding } from '../flow-binding.js';
 import {
   type JudgeClass,
+  type JudgeClassAssertableBy,
   type JudgeClassScope,
   type JudgedItem,
   type JudgedRunContext,
@@ -23,8 +24,11 @@ import {
   VERDICTS,
   type Verdict,
   judgeClassApplies,
+  whyNotAssertable,
 } from '../judgment-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
+import type { ReviewerBinding } from '../reviewer-binding.js';
+import { callerReviewerRole } from '../reviewer-role.js';
 import type { AppEnv } from '../types.js';
 import { captureTurnContext } from './judgment-context.js';
 import { captureFlowContext } from './judgment-flow-context.js';
@@ -52,6 +56,8 @@ export function judgmentsRouter(
   authorizer?: Authorizer,
   conversations?: ConversationBinding,
   flows?: FlowRegistryBinding,
+  /** Whose reviewer role a restricted judge class checks (T200). */
+  reviewers?: ReviewerBinding,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
@@ -72,9 +78,12 @@ export function judgmentsRouter(
       return fail('permission-denied', 'Judging needs a user or a service token.');
     }
 
-    const prepared = await prepareJudgment(c, body, runBinding, binding, authorizer);
+    const prepared = await prepareJudgment(c, body, runBinding, binding, authorizer, {
+      asserted,
+      reviewers,
+    });
     if (prepared.kind === 'err') return fail(prepared.code, prepared.message);
-    const { run, subject, projectId, itemValue, conversationId } = prepared;
+    const { run, subject, projectId, itemValue, conversationId, restricted } = prepared;
     const context = (await isFirstJudgment(binding, tenantId, body.runId))
       ? await captureContext({
           tenantId,
@@ -103,6 +112,7 @@ export function judgmentsRouter(
       verdict: body.verdict,
       ...(body.reason !== undefined && { reason: body.reason }),
       ...(body.judgeClassId !== undefined && { judgeClassId: body.judgeClassId }),
+      ...(restricted === true && { restricted }),
       assertedBy: asserted,
       ...(body.participantId !== undefined && { participantId: body.participantId }),
     });
@@ -239,7 +249,7 @@ export function judgeClassesRouter(
     };
     const parsed = parseClassBody(await c.req.json().catch(() => null));
     if (parsed.kind === 'err') return fail('bad-input', parsed.message);
-    const { scope, name, weight, description } = parsed.body;
+    const { scope, name, weight, description, assertableBy } = parsed.body;
     if (
       authorizer !== undefined &&
       !(await authorizer.can(c, 'admin', scopeRef(tenantId, scope)))
@@ -252,6 +262,7 @@ export function judgeClassesRouter(
       name,
       weight,
       ...(description !== undefined && { description }),
+      ...(assertableBy !== undefined && { assertableBy }),
     });
     if (outcome.kind === 'name-taken') {
       return fail('judge-class-name-taken', `A judge class named "${name}" already exists here.`);
@@ -332,19 +343,25 @@ export function judgeClassesRouter(
     const raw = (await c.req.json().catch(() => null)) as Record<string, unknown> | null;
     const weight = raw?.weight;
     const description = raw?.description;
+    const assertableBy =
+      raw?.assertableBy === undefined ? undefined : parseAssertableBy(raw.assertableBy);
     if (
       raw === null ||
       typeof raw !== 'object' ||
-      (weight === undefined && description === undefined) ||
+      (weight === undefined && description === undefined && assertableBy === undefined) ||
       (weight !== undefined && !isWeight(weight)) ||
-      (description !== undefined && typeof description !== 'string')
+      (description !== undefined && typeof description !== 'string') ||
+      typeof assertableBy === 'string'
     ) {
       c.status(statusFor('bad-input') as never);
       return c.json(
         toWireError(
           {
             code: 'bad-input',
-            message: 'Send weight (a number ≥ 0) and/or description (a string).',
+            message:
+              typeof assertableBy === 'string'
+                ? assertableBy
+                : 'Send weight (a number ≥ 0), description (a string) and/or assertableBy (who may assert the class, or null for anyone).',
           },
           requestId,
         ),
@@ -358,6 +375,7 @@ export function judgeClassesRouter(
       judgeClassId: found.id,
       ...(weight !== undefined && { weight: weight as number }),
       ...(description !== undefined && { description: description as string }),
+      ...(assertableBy !== undefined && { assertableBy }),
     });
     return updated === null ? classNotFound(c, found.id) : c.json(serializeJudgeClass(updated));
   });
@@ -382,6 +400,8 @@ type Prepared =
       readonly projectId: ProjectId;
       readonly itemValue?: unknown;
       readonly conversationId?: string;
+      /** The class was restricted and the caller met it. */
+      readonly restricted?: true;
     }
   | { readonly kind: 'err'; readonly code: string; readonly message: string };
 
@@ -396,6 +416,7 @@ async function prepareJudgment(
   runBinding: RunBinding,
   binding: JudgmentRegistryBinding,
   authorizer: Authorizer | undefined,
+  who: { readonly asserted: JudgmentAssertedBy; readonly reviewers: ReviewerBinding | undefined },
 ): Promise<Prepared> {
   const err = (code: string, message: string): Prepared => ({ kind: 'err', code, message });
   const tenantId = c.get('tenantId') as TenantId;
@@ -417,20 +438,37 @@ async function prepareJudgment(
   }
   const subject = subjectOf(run);
   const projectId = run.projectId as unknown as ProjectId;
-  if (
-    body.judgeClassId !== undefined &&
-    !(await classApplies(binding, tenantId, body.judgeClassId, { projectId, subject }))
-  ) {
-    return err(
-      'judge-class-not-applicable',
-      `Judge class "${body.judgeClassId}" doesn't exist or doesn't apply to this run's project or agent.`,
-    );
+  let restricted = false;
+  if (body.judgeClassId !== undefined) {
+    const judgeClass = await applicableClass(binding, tenantId, body.judgeClassId, {
+      projectId,
+      subject,
+    });
+    if (judgeClass === null) {
+      return err(
+        'judge-class-not-applicable',
+        `Judge class "${body.judgeClassId}" doesn't exist or doesn't apply to this run's project or agent.`,
+      );
+    }
+    if (judgeClass.assertableBy !== undefined) {
+      const reviewerRole = await callerReviewerRole(c, who.reviewers);
+      const why = whyNotAssertable(judgeClass.assertableBy, {
+        ...who.asserted,
+        ...(reviewerRole !== undefined && { reviewerRole }),
+      });
+      if (why !== undefined) {
+        return err('judge-class-not-allowed', `You can't judge as "${judgeClass.name}": ${why}.`);
+      }
+      restricted = true;
+    }
   }
   const copy = { input: run.input, output: run.output };
-  const turn =
-    run.agent !== undefined ? { conversationId: run.agent.conversationId as string } : {};
+  const extra = {
+    ...(run.agent !== undefined && { conversationId: run.agent.conversationId as string }),
+    ...(restricted && { restricted: true as const }),
+  };
   if (body.item.pointer === undefined)
-    return { kind: 'ok', run: copy, subject, projectId, ...turn };
+    return { kind: 'ok', run: copy, subject, projectId, ...extra };
   const found = resolvePointer(run.output, body.item.pointer);
   if (!found.found) {
     return err(
@@ -438,7 +476,7 @@ async function prepareJudgment(
       `Nothing at "${body.item.pointer}" in run "${body.runId}"'s output.`,
     );
   }
-  return { kind: 'ok', run: copy, subject, projectId, itemValue: found.value, ...turn };
+  return { kind: 'ok', run: copy, subject, projectId, itemValue: found.value, ...extra };
 }
 
 /** Whether the run has no live judgment yet (its copy is stored with the first). */
@@ -484,15 +522,15 @@ async function isFirstJudgment(
   return page.data.length === 0;
 }
 
-/** Whether a live class exists and its scope covers the run. */
-async function classApplies(
+/** The live class, when it exists and its scope covers the run; else `null`. */
+async function applicableClass(
   binding: JudgmentRegistryBinding,
   tenantId: TenantId,
   judgeClassId: string,
   run: { readonly projectId: ProjectId; readonly subject: JudgedSubject },
-): Promise<boolean> {
+): Promise<JudgeClass | null> {
   const judgeClass = await binding.getClass({ tenantId, judgeClassId });
-  return judgeClass !== null && judgeClassApplies(judgeClass.scope, run);
+  return judgeClass !== null && judgeClassApplies(judgeClass.scope, run) ? judgeClass : null;
 }
 
 // ---------- request parsing ----------
@@ -573,6 +611,47 @@ interface ClassBody {
   readonly name: string;
   readonly weight: number;
   readonly description?: string;
+  readonly assertableBy?: JudgeClassAssertableBy;
+}
+
+const ASSERTABLE_BY_USAGE =
+  'assertableBy says who may assert the class: { minReviewerRole?: "standard" | "senior" | "admin", principalKinds?: ["user" | "service", …], principalIds?: [id, …] }, with at least one of them.';
+
+/** `assertableBy`: a restriction, `null` (on an update: lift it), or what's wrong. */
+function parseAssertableBy(raw: unknown): JudgeClassAssertableBy | null | string {
+  if (raw === null) return null;
+  if (typeof raw !== 'object' || Array.isArray(raw)) return ASSERTABLE_BY_USAGE;
+  const b = raw as Record<string, unknown>;
+  const keys = Object.keys(b);
+  const known = ['minReviewerRole', 'principalKinds', 'principalIds'];
+  if (keys.length === 0 || keys.some((k) => !known.includes(k))) return ASSERTABLE_BY_USAGE;
+  const role = b.minReviewerRole;
+  if (role !== undefined && !(typeof role === 'string' && role in REVIEWER_ROLE_RANK)) {
+    return ASSERTABLE_BY_USAGE;
+  }
+  const kinds = b.principalKinds;
+  if (
+    kinds !== undefined &&
+    !(
+      Array.isArray(kinds) &&
+      kinds.length > 0 &&
+      kinds.every((k) => k === 'user' || k === 'service')
+    )
+  ) {
+    return ASSERTABLE_BY_USAGE;
+  }
+  const ids = b.principalIds;
+  if (
+    ids !== undefined &&
+    !(Array.isArray(ids) && ids.length > 0 && ids.length <= 100 && ids.every(nonEmpty))
+  ) {
+    return ASSERTABLE_BY_USAGE;
+  }
+  return {
+    ...(role !== undefined && { minReviewerRole: role as ReviewerRole }),
+    ...(kinds !== undefined && { principalKinds: kinds as ('user' | 'service')[] }),
+    ...(ids !== undefined && { principalIds: ids as string[] }),
+  };
 }
 
 function parseClassBody(raw: unknown): Parsed<ClassBody> {
@@ -587,6 +666,8 @@ function parseClassBody(raw: unknown): Parsed<ClassBody> {
   }
   const scope = parseClassScope(b.scope);
   if (typeof scope === 'string') return err(scope);
+  const assertableBy = b.assertableBy === undefined ? undefined : parseAssertableBy(b.assertableBy);
+  if (typeof assertableBy === 'string') return err(assertableBy);
   return {
     kind: 'ok',
     body: {
@@ -594,6 +675,7 @@ function parseClassBody(raw: unknown): Parsed<ClassBody> {
       name: b.name,
       weight: b.weight,
       ...(typeof b.description === 'string' && { description: b.description }),
+      ...(assertableBy !== undefined && assertableBy !== null && { assertableBy }),
     },
   };
 }
@@ -712,6 +794,7 @@ function serializeJudgment(j: Judgment): Record<string, unknown> {
     verdict: j.verdict,
     ...(j.reason !== undefined && { reason: j.reason }),
     ...(j.judgeClassId !== undefined && { judgeClassId: j.judgeClassId }),
+    ...(j.restricted === true && { restricted: true }),
     assertedBy: j.assertedBy,
     ...(j.participantId !== undefined && { participantId: j.participantId }),
     createdAt: j.createdAt,
@@ -736,6 +819,7 @@ function serializeJudgeClass(k: JudgeClass): Record<string, unknown> {
     name: k.name,
     weight: k.weight,
     ...(k.description !== undefined && { description: k.description }),
+    ...(k.assertableBy !== undefined && { assertableBy: k.assertableBy }),
     createdAt: k.createdAt,
     updatedAt: k.updatedAt,
     ...(k.unregisteredAt !== undefined && { unregisteredAt: k.unregisteredAt }),

package/src/routes/live-scope-wire.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { LiveScope, OrgId, ProjectId } from '@kindgi/types';
+
+import { parseSegmentsBody } from './segments.js';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** A live scope on the wire: `{kind}` plus the id or path it needs. */
+export type WireLiveScope =
+  | { readonly kind: 'tenant' }
+  | { readonly kind: 'org'; readonly orgId: string }
+  | { readonly kind: 'project'; readonly projectId: string }
+  | {
+      readonly kind: 'segment';
+      readonly projectId: string;
+      readonly path: readonly { readonly key: string; readonly value: string }[];
+    };
+
+export function liveScopeToWire(scope: LiveScope): WireLiveScope {
+  switch (scope.kind) {
+    case 'tenant':
+      return { kind: 'tenant' };
+    case 'org':
+      return { kind: 'org', orgId: scope.orgId as unknown as string };
+    case 'project':
+      return { kind: 'project', projectId: scope.projectId as unknown as string };
+    case 'segment':
+      return {
+        kind: 'segment',
+        projectId: scope.projectId as unknown as string,
+        path: scope.path.map(({ key, value }) => ({ key, value })),
+      };
+  }
+}
+
+/**
+ * A live scope from a request body (`scope`): `{kind: 'tenant'}`,
+ * `{kind: 'org', orgId}`, `{kind: 'project', projectId}` or
+ * `{kind: 'segment', projectId, path: [{key, value}, …]}`.
+ */
+export function parseLiveScopeBody(
+  raw: unknown,
+):
+  | { readonly kind: 'ok'; readonly scope: LiveScope }
+  | { readonly kind: 'err'; readonly message: string } {
+  const b = (raw ?? {}) as Record<string, unknown>;
+  const id = (field: 'orgId' | 'projectId'): string | undefined => {
+    const v = b[field];
+    return typeof v === 'string' && UUID_RE.test(v) ? v : undefined;
+  };
+  switch (b.kind) {
+    case 'tenant':
+      return { kind: 'ok', scope: { kind: 'tenant' } };
+    case 'org': {
+      const orgId = id('orgId');
+      if (orgId === undefined)
+        return { kind: 'err', message: '`scope.orgId` must be an org id (a UUID)' };
+      return { kind: 'ok', scope: { kind: 'org', orgId: orgId as OrgId } };
+    }
+    case 'project': {
+      const projectId = id('projectId');
+      if (projectId === undefined) {
+        return { kind: 'err', message: '`scope.projectId` must be a project id (a UUID)' };
+      }
+      return { kind: 'ok', scope: { kind: 'project', projectId: projectId as ProjectId } };
+    }
+    case 'segment': {
+      const projectId = id('projectId');
+      if (projectId === undefined) {
+        return { kind: 'err', message: '`scope.projectId` must be a project id (a UUID)' };
+      }
+      const path = parseSegmentsBody(b.path, 'scope.path');
+      if (path.kind === 'err') return path;
+      if (path.segments === undefined) {
+        return { kind: 'err', message: '`scope.path` needs at least one segment' };
+      }
+      return {
+        kind: 'ok',
+        scope: { kind: 'segment', projectId: projectId as ProjectId, path: path.segments },
+      };
+    }
+    default:
+      return {
+        kind: 'err',
+        message: '`scope.kind` must be one of tenant, org, project, segment',
+      };
+  }
+}

package/src/routes/policies.ts

@@ -11,6 +11,8 @@ import {
   type Policy,
   type PolicyKind,
   type PolicyRegistryBinding,
+  type PolicyScopeChanged,
+  type PolicyScopeTaken,
   isAppliedPolicyKind,
   validatePolicySpec,
 } from '@kindgi/policy-contract';
@@ -27,9 +29,12 @@ import { clampLimit } from './pagination.js';
  * that kind. The route validates the top-level shape (id, tenantId,
  * semver version, kind ∈ closed enum, spec is an object), and `spec`
  * against its kind's contract where `@kindgi/policy-contract` has one
- * (`tool-errors`, `hitl`) — a policy that couldn't be applied is refused
- * here, not found out on a turn. Other kinds' specs are their runtime
- * consumer's to validate.
+ * (`tool-errors`, `hitl`, `retention`) — a policy that couldn't be
+ * applied is refused here, not found out on a turn or a sweep. Other
+ * kinds' specs are their runtime consumer's to validate. A kind that
+ * holds a scope (`policyScope`: a retention policy, its domain) gets one
+ * policy per scope; the binding enforces it (`409 policy-scope-taken`,
+ * `409 policy-scope-changed`).
  *
  * Enforcement is out of scope. This is the *registry* surface only.
  * Runtime consumers (e.g. `@kindgi/capabilities` `route` for
@@ -255,6 +260,10 @@ export function policiesRouter(binding: PolicyRegistryBinding): Hono<AppEnv> {
         ),
       );
     }
+    if (outcome.kind === 'scope-taken' || outcome.kind === 'scope-changed') {
+      c.status(statusFor(`policy-${outcome.kind}`) as never);
+      return c.json(toWireError(scopeError(outcome, 'publish'), requestId));
+    }
     c.status(201);
     return c.json({ policyId: outcome.policyId, version: outcome.version });
   });
@@ -305,6 +314,10 @@ export function policiesRouter(binding: PolicyRegistryBinding): Hono<AppEnv> {
         ),
       );
     }
+    if (outcome.kind === 'scope-taken' || outcome.kind === 'scope-changed') {
+      c.status(statusFor(`policy-${outcome.kind}`) as never);
+      return c.json(toWireError(scopeError(outcome, 'reinstate'), requestId));
+    }
     return c.json({
       policyId: outcome.policyId,
       version: outcome.version,
@@ -315,6 +328,51 @@ export function policiesRouter(binding: PolicyRegistryBinding): Hono<AppEnv> {
   return r;
 }
 
+/**
+ * The 409 for a policy whose scope (`policyScope`) another policy holds,
+ * or that a version would move: for `retention`, a second policy for a
+ * domain, which a tenant can't have.
+ */
+function scopeError(
+  outcome: PolicyScopeTaken | PolicyScopeChanged,
+  action: 'publish' | 'reinstate',
+): { code: string; message: string } & Record<string, unknown> {
+  const { policyId, version, policyKind, scope } = outcome;
+  const retention = policyKind === 'retention';
+  if (outcome.kind === 'scope-taken') {
+    const { heldBy } = outcome;
+    const message = !retention
+      ? `Policy "${heldBy}" already holds "${scope}" for ${policyKind} policies.`
+      : action === 'publish'
+        ? `Retention domain "${scope}" is already covered by policy "${heldBy}": a tenant has one retention policy per domain, and one for "*". Publish a new version of "${heldBy}" instead, or unregister it first.`
+        : `Retention domain "${scope}" is now covered by policy "${heldBy}", so reinstating "${policyId}" ${version} would make two: a tenant has one retention policy per domain, and one for "*". Unregister "${heldBy}" first.`;
+    return {
+      code: 'policy-scope-taken',
+      message,
+      policyId,
+      version,
+      policyKind,
+      scope,
+      heldBy,
+    };
+  }
+  const { previousScope } = outcome;
+  const message = !retention
+    ? `Policy "${policyId}" holds "${previousScope}"; version ${version} can't move it to "${scope}".`
+    : action === 'publish'
+      ? `Policy "${policyId}" covers retention domain "${previousScope}", and a new version can't move it to "${scope}". Publish a policy for "${scope}" under a new id.`
+      : `Version ${version} of policy "${policyId}" covers retention domain "${scope}", but its other versions cover "${previousScope}": a policy keeps one domain. Publish it under a new id instead.`;
+  return {
+    code: 'policy-scope-changed',
+    message,
+    policyId,
+    version,
+    policyKind,
+    scope,
+    previousScope,
+  };
+}
+
 function serializePolicy(p: Policy): Record<string, unknown> {
   return {
     id: p.id,