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

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,

package/src/routes/projects.ts

@@ -10,6 +10,7 @@ import type {
   ProjectBinding,
   ProjectMembership,
   ProjectMembershipBinding,
+  ProjectMembershipUpdateRoleOutcome,
   ProjectPatch,
   ProjectRole,
   ProjectSpec,
@@ -20,6 +21,7 @@ import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
 import {
+  membershipNotKeptInStepError,
   orgNotFoundError,
   projectDefaultAlreadyExistsError,
   slugConflictError,
@@ -78,6 +80,39 @@ export function projectsRouter(
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
+  /**
+   * Change a member's role. With an authorizer, the row and its FGA tuple
+   * change together through the tenant-hierarchy binding, or the change
+   * is refused; without one, the membership binding alone.
+   */
+  async function updateMemberRole(
+    tenantId: TenantId,
+    projectId: ProjectId,
+    userId: UserId,
+    role: ProjectRole,
+  ): Promise<
+    | { readonly kind: 'done'; readonly outcome: ProjectMembershipUpdateRoleOutcome }
+    | { readonly kind: 'refused'; readonly error: ReturnType<typeof membershipNotKeptInStepError> }
+  > {
+    if (authorizer === undefined) {
+      return {
+        kind: 'done',
+        outcome: await membershipBinding.updateRole(tenantId, projectId, userId, role),
+      };
+    }
+    if (tenantHierarchy.updateProjectMemberRole === undefined) {
+      return { kind: 'refused', error: membershipNotKeptInStepError('updateProjectMemberRole') };
+    }
+    const res = await tenantHierarchy.updateProjectMemberRole({
+      tenantId,
+      projectId,
+      userId,
+      role,
+    });
+    if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    return { kind: 'done', outcome: res.value };
+  }
+
   // ---------- GET /default (literal segment; must precede /:projectId) ----------
   r.get('/default', async (c) => {
     const requestId = c.get('requestId');
@@ -420,7 +455,19 @@ export function projectsRouter(
     const tenantId = c.get('tenantId') as TenantId;
     const projectId = c.req.param('projectId') as ProjectId;
     const userId = c.req.param('userId') as UserId;
-    await membershipBinding.remove(tenantId, projectId, userId);
+    // With an authorizer, the row and its FGA tuple go together, or not
+    // at all: removing the row alone would leave the permission in place.
+    if (authorizer !== undefined) {
+      if (tenantHierarchy.removeProjectMember === undefined) {
+        const refusal = membershipNotKeptInStepError('removeProjectMember');
+        c.status(statusFor(refusal.code) as never);
+        return c.json(toWireError(refusal, c.get('requestId')));
+      }
+      const res = await tenantHierarchy.removeProjectMember({ tenantId, projectId, userId });
+      if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    } else {
+      await membershipBinding.remove(tenantId, projectId, userId);
+    }
     c.status(204);
     return c.body(null);
   });
@@ -460,7 +507,12 @@ export function projectsRouter(
         ),
       );
     }
-    const outcome = await membershipBinding.updateRole(tenantId, projectId, userId, b.role);
+    const updated = await updateMemberRole(tenantId, projectId, userId, b.role);
+    if (updated.kind === 'refused') {
+      c.status(statusFor(updated.error.code) as never);
+      return c.json(toWireError(updated.error, requestId));
+    }
+    const { outcome } = updated;
     if (outcome.kind === 'project-membership-not-found') {
       c.status(statusFor('project-membership-not-found') as never);
       return c.json(

package/src/routes/retention.ts

@@ -62,15 +62,21 @@ export function retentionRouter(binding: RetentionBinding, authorizer?: Authoriz
     const limit = clampLimit(url.searchParams.get('limit') ?? undefined);
     const pastGraceRaw = url.searchParams.get('pastGraceOnly');
     const pastGraceOnly = pastGraceRaw === 'true';
+    const cursor = url.searchParams.get('cursor') ?? '';
 
-    const page = await binding.scheduled({
+    const { hasMore, nextCursor, ...page } = await binding.scheduled({
       tenantId,
       limit,
       pastGraceOnly,
       ...(domain !== undefined && { domain }),
+      ...(cursor !== '' && { cursor }),
     });
 
-    return c.json(page);
+    return c.json({
+      ...page,
+      hasMore: hasMore ?? someDomainFilled(page.data, limit),
+      ...(nextCursor !== undefined && { nextCursor }),
+    });
   });
 
   r.post('/sweep', async (c) => {
@@ -153,6 +159,19 @@ export function retentionRouter(binding: RetentionBinding, authorizer?: Authoriz
   return r;
 }
 
+/**
+ * A runtime that doesn't report `hasMore`: there may be more when some
+ * domain's rows fill `limit` (each domain is read up to `limit`).
+ */
+function someDomainFilled(
+  data: readonly { readonly domain: RetentionDomain }[],
+  limit: number,
+): boolean {
+  const perDomain = new Map<RetentionDomain, number>();
+  for (const row of data) perDomain.set(row.domain, (perDomain.get(row.domain) ?? 0) + 1);
+  return [...perDomain.values()].some((n) => n >= limit);
+}
+
 function parseDomain(raw: string | null | undefined): RetentionDomain | 'invalid' | undefined {
   if (raw === null || raw === undefined || raw === '') return undefined;
   if ((RETENTION_DOMAINS as readonly string[]).includes(raw)) return raw as RetentionDomain;

package/src/routes/reviewers.ts

@@ -3,10 +3,11 @@
 
 import { Hono } from 'hono';
 
-import type { ReviewerRole } from '@kindgi/authz';
+import { type ReviewerRole, ref } from '@kindgi/authz';
 import type { Cursor, ReviewerId, TenantId, UserId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { ReviewerRecord, ReviewerRegistryBinding } from '../reviewer-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
@@ -20,8 +21,9 @@ import { clampLimit } from './pagination.js';
  * inside `approvalsRouter`: registering a reviewer is an admin surface
  * action, not a reviewer-only one, so requiring a `reviewerRole` on the
  * caller would be circular ("only reviewers can appoint reviewers").
- * The caller still needs a valid bearer token — the `/v1/*` auth chain
- * covers that upstream.
+ * With authorization enforced, registering or unregistering needs
+ * `admin` on the tenant; reading the roster needs only a valid bearer
+ * token (the `/v1/*` auth chain upstream).
  *
  * Mounted BEFORE `approvalsRouter` on the parent `/v1` router so path
  * matching resolves `/v1/approvals/reviewers/*` here rather than being
@@ -29,9 +31,26 @@ import { clampLimit } from './pagination.js';
  */
 const ROLE_VALUES: ReadonlySet<ReviewerRole> = new Set(['standard', 'senior', 'admin']);
 
-export function reviewersRouter(binding: ReviewerRegistryBinding): Hono<AppEnv> {
+export function reviewersRouter(
+  binding: ReviewerRegistryBinding,
+  /**
+   * When set, registering or unregistering a reviewer needs `admin` on
+   * the tenant: a reviewer (an `admin` one above all) decides approvals.
+   * Reading the list doesn't.
+   */
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
+  if (authorizer !== undefined) {
+    r.use('*', async (c, next) => {
+      if (c.req.method === 'GET') return next();
+      const tenantId = c.get('tenantId') as TenantId;
+      const mw = authorizer.authorize('admin', () => ref('tenant', tenantId as unknown as string));
+      return mw(c, next);
+    });
+  }
+
   // ---------- GET / (list, cursor-paginated) ----------
   r.get('/', async (c) => {
     const requestId = c.get('requestId');