@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/routes/eval-comparison.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AgentId } from '@kindgi/agents';
+import type { ProjectId, Semver } from '@kindgi/types';
+
+import type { EvalBaseline, EvalComparison } from '../eval-run-binding.js';
+import { DEFAULT_COMPARISON } from '../judged-dispatcher.js';
+
+const MAX_REPETITIONS = 10;
+const MAX_K = 100;
+
+function obj(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function parseLive(raw: unknown): EvalBaseline | string {
+  const live = obj(raw);
+  if (live === undefined) return '`baseline.live` must be an object';
+  const segments = live.segments === undefined ? undefined : obj(live.segments);
+  const stringsOnly =
+    segments !== undefined && Object.values(segments).every((v) => typeof v === 'string');
+  if (live.segments !== undefined && !stringsOnly) {
+    return '`baseline.live.segments` must be an object of strings';
+  }
+  if (live.projectId !== undefined && typeof live.projectId !== 'string') {
+    return '`baseline.live.projectId` must be a string';
+  }
+  return {
+    live: {
+      ...(typeof live.projectId === 'string' && { projectId: live.projectId as ProjectId }),
+      ...(segments !== undefined && { segments: segments as Record<string, string> }),
+    },
+  };
+}
+
+function parseBaseline(raw: unknown): EvalBaseline | string {
+  if (raw === 'recorded') return 'recorded';
+  const o = obj(raw);
+  if (o === undefined) {
+    return "`baseline` must be 'recorded', { agentId, version } or { live: { projectId?, segments? } }";
+  }
+  if (o.live !== undefined) return parseLive(o.live);
+  if (typeof o.agentId !== 'string' || o.agentId === '' || typeof o.version !== 'string') {
+    return '`baseline` as a version needs `agentId` and `version`';
+  }
+  return { agentId: o.agentId as AgentId, version: o.version as Semver };
+}
+
+function integerIn(raw: unknown, name: string, max: number): number | string {
+  return typeof raw === 'number' && Number.isInteger(raw) && raw >= 1 && raw <= max
+    ? raw
+    : `\`${name}\` must be an integer from 1 to ${max}`;
+}
+
+/**
+ * A comparison eval run's settings from the start body: `baseline`,
+ * `reads`, `repetitions` and `k`. `undefined` when none is given (the
+ * defaults apply); an error message for a bad one.
+ */
+export function parseComparison(
+  b: Readonly<Record<string, unknown>>,
+):
+  | { readonly kind: 'ok'; readonly value?: EvalComparison }
+  | { readonly kind: 'err'; readonly message: string } {
+  const { baseline, reads, repetitions, k } = b;
+  if (
+    baseline === undefined &&
+    reads === undefined &&
+    repetitions === undefined &&
+    k === undefined
+  ) {
+    return { kind: 'ok' };
+  }
+  const parsedBaseline =
+    baseline === undefined ? DEFAULT_COMPARISON.baseline : parseBaseline(baseline);
+  if (typeof parsedBaseline === 'string' && parsedBaseline !== 'recorded') {
+    return { kind: 'err', message: parsedBaseline };
+  }
+  if (reads !== undefined && reads !== 'recorded' && reads !== 'live') {
+    return { kind: 'err', message: "`reads` must be 'recorded' or 'live'" };
+  }
+  const reps =
+    repetitions === undefined
+      ? DEFAULT_COMPARISON.repetitions
+      : integerIn(repetitions, 'repetitions', MAX_REPETITIONS);
+  if (typeof reps === 'string') return { kind: 'err', message: reps };
+  const topK = k === undefined ? DEFAULT_COMPARISON.k : integerIn(k, 'k', MAX_K);
+  if (typeof topK === 'string') return { kind: 'err', message: topK };
+  return {
+    kind: 'ok',
+    value: {
+      baseline: parsedBaseline,
+      reads: reads ?? DEFAULT_COMPARISON.reads,
+      repetitions: reps,
+      k: topK,
+    },
+  };
+}

package/src/routes/eval-runs.ts

@@ -10,6 +10,7 @@ import { statusFor, toWireError } from '../errors.js';
 import {
   type AgentRef,
   EVAL_RUN_STATUSES,
+  type EvalComparison,
   type EvalRun,
   type EvalRunBinding,
   type EvalRunFilter,
@@ -17,6 +18,7 @@ import {
   type FlowRef,
 } from '../eval-run-binding.js';
 import type { AppEnv } from '../types.js';
+import { parseComparison } from './eval-comparison.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
 import { formatSseFrame } from './sse.js';
@@ -93,6 +95,7 @@ function startRouter(binding: EvalRunBinding): Hono<AppEnv> {
       ...(parsed.value.correlationId !== undefined && {
         correlationId: parsed.value.correlationId,
       }),
+      ...(parsed.value.comparison !== undefined && { comparison: parsed.value.comparison }),
     });
     if (outcome.kind === 'suite-not-found') {
       c.status(statusFor('eval-suite-not-found') as never);
@@ -454,6 +457,7 @@ function serializeEvalRun(run: EvalRun): Record<string, unknown> {
     ...(run.result !== undefined && { result: run.result }),
     ...(run.error !== undefined && { error: run.error }),
     ...(run.correlationId !== undefined && { correlationId: run.correlationId }),
+    ...(run.comparison !== undefined && { comparison: run.comparison }),
   };
 }
 
@@ -486,6 +490,7 @@ interface ParsedStartBody {
   readonly flowRef?: FlowRef;
   readonly dryRun?: boolean;
   readonly correlationId?: string;
+  readonly comparison?: EvalComparison;
 }
 
 function parseStartBody(
@@ -618,6 +623,11 @@ function parseStartBody(
     };
   }
 
+  const comparison = parseComparison(b);
+  if (comparison.kind === 'err') {
+    return { kind: 'err', error: { code: 'bad-input', message: comparison.message } };
+  }
+
   return {
     kind: 'ok',
     value: {
@@ -626,6 +636,7 @@ function parseStartBody(
       ...(flowRef !== undefined && { flowRef }),
       ...(dryRun !== undefined && { dryRun }),
       ...(correlationId !== undefined && { correlationId: correlationId as string }),
+      ...(comparison.value !== undefined && { comparison: comparison.value }),
     },
   };
 }

package/src/routes/flows.ts

@@ -4,12 +4,16 @@
 import { Hono } from 'hono';
 
 import { type Principal, ref, tuplesForCreate } from '@kindgi/authz';
-import { type Flow, type FlowError, loadFlow } from '@kindgi/flow';
+import { type Flow, type FlowError, flowPinsDigest, loadFlow } from '@kindgi/flow';
 import type { Cursor, FlowId, ProjectId, TenantId, UserId } from '@kindgi/types';
 
+import type { AgentRegistryBinding } from '../agent-binding.js';
+import type { UnpinnableRef } from '../agent-pins.js';
 import { statusFor, toWireError } from '../errors.js';
-import type { FlowRegistryBinding } from '../flow-binding.js';
+import type { FlowRegistryBinding, FlowVersionRecord } from '../flow-binding.js';
+import { resolveFlowPins } from '../flow-pins.js';
 import type { Authorizer } from '../middleware/authorize.js';
+import type { ToolRegistryBinding } from '../tool-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
@@ -30,8 +34,19 @@ import { parseScopeParams } from './scope-params.js';
  * Run initiation stays at `POST /v1/runs` (one primitive,
  * discriminated subject). No
  * `/v1/flows/:flowId/run` route is added here.
+ *
+ * With `pinning` (the tool and agent registries), a published version is
+ * pinned: each tool it runs, and each agent it runs at no named version,
+ * resolves once, at publish, to the latest version, which every run of
+ * that version uses (`pins`, see `resolveFlowPins`); one with no
+ * published version refuses the publish. Without it, versions carry no
+ * pins and bind the latest versions per run.
  */
-export function flowsRouter(binding: FlowRegistryBinding, authorizer?: Authorizer): Hono<AppEnv> {
+export function flowsRouter(
+  binding: FlowRegistryBinding,
+  authorizer?: Authorizer,
+  pinning?: { readonly tools: ToolRegistryBinding; readonly agents: AgentRegistryBinding },
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
   // Authorization — mirrors agents 1:1. Check the resource directly;
@@ -275,13 +290,23 @@ export function flowsRouter(binding: FlowRegistryBinding, authorizer?: Authorize
       );
     }
 
+    // Pin the version: every tool and unversioned agent resolves now,
+    // once, to the version its runs use. One with no published version
+    // refuses the publish rather than store a partly pinned version.
+    const pinned = await pinFlow(pinning, tenantId, loaded.value);
+    if (pinned.kind === 'unpinnable') {
+      c.status(statusFor('validation-failed') as never);
+      return c.json(toWireError(unpinnableFlow(loaded.value, pinned.issues), requestId));
+    }
+    const flow = pinned.flow;
+
     const principal = c.get('principal') as Principal | undefined;
     const creatorUserId =
       principal?.actor.kind === 'user' ? (principal.actor.id as UserId) : undefined;
     const outcome = await binding.publish({
       tenantId,
       projectId,
-      flow: loaded.value,
+      flow,
       enqueueTuples: (flowId) =>
         tuplesForCreate({ kind: 'flow', id: flowId as FlowId, tenantId, projectId }, creatorUserId),
     });
@@ -383,7 +408,36 @@ export function flowsRouter(binding: FlowRegistryBinding, authorizer?: Authorize
   return r;
 }
 
-function serializeGraph(g: Flow): Record<string, unknown> {
+/** The flow with its pins, or the references with no published version; as it is without `pinning`. */
+async function pinFlow(
+  pinning:
+    | { readonly tools: ToolRegistryBinding; readonly agents: AgentRegistryBinding }
+    | undefined,
+  tenantId: TenantId,
+  flow: Flow,
+): Promise<
+  | { readonly kind: 'ok'; readonly flow: Flow }
+  | { readonly kind: 'unpinnable'; readonly issues: readonly UnpinnableRef[] }
+> {
+  if (pinning === undefined) return { kind: 'ok', flow };
+  const resolved = await resolveFlowPins(pinning.tools, pinning.agents, tenantId, flow);
+  if (resolved.kind === 'unpinnable') return resolved;
+  return {
+    kind: 'ok',
+    flow: { ...flow, pins: resolved.pins, pinsDigest: flowPinsDigest(resolved.pins) },
+  };
+}
+
+/** The `validation-failed` error naming each tool or agent a flow runs that isn't published. */
+function unpinnableFlow(flow: Flow, issues: readonly UnpinnableRef[]) {
+  return {
+    code: 'validation-failed' as const,
+    message: `Flow "${flow.id as unknown as string}" runs tools or agents that aren't published (${issues.length} issue${issues.length === 1 ? '' : 's'})`,
+    issues: issues as unknown as Record<string, unknown>[],
+  };
+}
+
+function serializeGraph(g: FlowVersionRecord): Record<string, unknown> {
   return {
     id: g.id as unknown as string,
     version: g.version,
@@ -393,6 +447,10 @@ function serializeGraph(g: Flow): Record<string, unknown> {
     edges: g.edges,
     ...(g.maxParallelism !== undefined && { maxParallelism: g.maxParallelism }),
     ...(g.metadata !== undefined && { metadata: g.metadata }),
+    ...(g.pins !== undefined && { pins: g.pins }),
+    ...(g.pinsDigest !== undefined && { pinsDigest: g.pinsDigest }),
+    ...(g.derivedFrom !== undefined && { derivedFrom: g.derivedFrom }),
+    ...(g.unregisteredAt !== undefined && { unregisteredAt: g.unregisteredAt }),
   };
 }
 

package/src/routes/hierarchy-errors.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Wire errors the tenant-hierarchy routes (orgs, teams, projects) share,
+ * so a conflict reads the same whichever route or write path (with or
+ * without an authorizer) produced it.
+ */
+
+/** A hierarchy resource, as its wire errors name it. */
+export type HierarchyResource = 'org' | 'team' | 'project';
+
+/**
+ * `409 slug-conflict`: another `resource` has `slug` where it must be
+ * unique. An org's and a team's slug are unique in the tenant; a
+ * project's in its org, and a project without an org's among the
+ * projects without one.
+ */
+export function slugConflictError(resource: HierarchyResource, slug: string) {
+  return {
+    code: 'slug-conflict',
+    message:
+      resource === 'project'
+        ? `Another project in its org has the slug "${slug}" (for a project without an org: another project without one)`
+        : `Another ${resource} in the tenant has the slug "${slug}"`,
+    resource,
+    slug,
+  } as const;
+}
+
+/**
+ * `409 slug-conflict` on deleting an org: its projects would leave it
+ * with `slugs` that projects without an org already have.
+ */
+export function orgDeleteSlugConflictError(slugs: readonly string[]) {
+  const named = slugs.map((s) => `"${s}"`).join(', ');
+  return {
+    code: 'slug-conflict',
+    message: `Deleting the org would leave its projects ${named} without an org, where other projects already have those slugs. Rename or move them first.`,
+    resource: 'project',
+    slugs,
+  } as const;
+}
+
+/** `409 project-default-already-exists`: the tenant has a Default project. */
+export function projectDefaultAlreadyExistsError() {
+  return {
+    code: 'project-default-already-exists',
+    message: 'The tenant already has a Default project',
+  } as const;
+}

package/src/routes/identity.ts

@@ -11,6 +11,8 @@ import type {
   SessionSummary,
   UserRecord,
 } from '../identity-directory-binding.js';
+import type { ReviewerBinding } from '../reviewer-binding.js';
+import { callerReviewerRole } from '../reviewer-role.js';
 import type { SessionStoreBinding } from '../session-store-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
@@ -47,10 +49,16 @@ export interface IdentityRouterOptions {
    * deployments that don't wire an OAuth surface.
    */
   readonly sessionStore?: SessionStoreBinding;
+  /**
+   * Optional. When present, `whoami` reports the reviewer role of a
+   * caller whose token carries none from the roster, as the approvals
+   * routes resolve it.
+   */
+  readonly reviewerBinding?: ReviewerBinding;
 }
 
 export function identityRouter(options: IdentityRouterOptions = {}): Hono<AppEnv> {
-  const { directory, sessionStore } = options;
+  const { directory, sessionStore, reviewerBinding } = options;
   const r = new Hono<AppEnv>();
 
   // ---------- GET / whoami ----------
@@ -62,7 +70,7 @@ export function identityRouter(options: IdentityRouterOptions = {}): Hono<AppEnv
     const userId = c.get('userId') as UserId | undefined;
     const providerId = c.get('providerId') as string | undefined;
     const scopes = (c.get('scopes') as readonly string[] | undefined) ?? [];
-    const reviewerRole = c.get('reviewerRole') as string | undefined;
+    const reviewerRole = await callerReviewerRole(c, reviewerBinding);
 
     const body: Record<string, unknown> = { tenantId };
     if (sessionId !== undefined) body.sessionId = sessionId;