@kindgi/api 0.1.3 → 0.1.4-rc.1

package/src/routes/eval-runs.ts

@@ -10,13 +10,17 @@ import { statusFor, toWireError } from '../errors.js';
 import {
   type AgentRef,
   EVAL_RUN_STATUSES,
+  type EvalComparison,
   type EvalRun,
   type EvalRunBinding,
   type EvalRunFilter,
   type EvalRunStatus,
   type FlowRef,
 } from '../eval-run-binding.js';
+import { VERSIONS_NEED_A_FLOW } from '../judged-dispatcher.js';
 import type { AppEnv } from '../types.js';
+import { parseComparison } from './eval-comparison.js';
+import { type FlowVersionsCheck, checkFlowVersions } from './eval-versions.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
 import { formatSseFrame } from './sse.js';
@@ -45,16 +49,49 @@ export interface EvalRunsRouters {
   readonly readback: Hono<AppEnv>;
 }
 
-export function evalRunsRouters(binding: EvalRunBinding): EvalRunsRouters {
+/**
+ * `versionsCheck`: where a flow candidate's `versions` are checked
+ * against the flow version at start (without it, they're applied as
+ * given).
+ */
+export function evalRunsRouters(
+  binding: EvalRunBinding,
+  versionsCheck?: FlowVersionsCheck,
+): EvalRunsRouters {
   return {
-    start: startRouter(binding),
+    start: startRouter(binding, versionsCheck),
     readback: readbackRouter(binding),
   };
 }
 
 // ---------- POST /v1/eval-suites/:suiteId/runs ----------
 
-function startRouter(binding: EvalRunBinding): Hono<AppEnv> {
+/** The `validation-failed` error for a flow candidate's `versions` that don't fit the flow; `undefined` when they do. */
+async function versionsRefusal(
+  check: FlowVersionsCheck | undefined,
+  tenantId: TenantId,
+  start: ParsedStartBody,
+) {
+  const versions = start.comparison?.versions;
+  const flowRef = start.flowRef;
+  if (check === undefined || versions === undefined || flowRef?.version === undefined) {
+    return undefined;
+  }
+  const issues = await checkFlowVersions(
+    check,
+    tenantId,
+    { flowId: flowRef.flowId as unknown as string, version: flowRef.version },
+    versions,
+  );
+  if (issues.length === 0) return undefined;
+  return {
+    code: 'validation-failed' as const,
+    message: `The versions don't fit flow ${flowRef.flowId as unknown as string} ${flowRef.version} (${issues.length} issue${issues.length === 1 ? '' : 's'})`,
+    issues: issues as unknown as Record<string, unknown>[],
+  };
+}
+
+function startRouter(binding: EvalRunBinding, versionsCheck?: FlowVersionsCheck): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
   r.post('/:suiteId/runs', async (c) => {
@@ -82,6 +119,11 @@ function startRouter(binding: EvalRunBinding): Hono<AppEnv> {
       c.status(statusFor(parsed.error.code) as never);
       return c.json(toWireError(parsed.error, requestId));
     }
+    const refusal = await versionsRefusal(versionsCheck, tenantId, parsed.value);
+    if (refusal !== undefined) {
+      c.status(statusFor(refusal.code) as never);
+      return c.json(toWireError(refusal, requestId));
+    }
 
     const outcome = await binding.start({
       tenantId,
@@ -93,6 +135,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 +497,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 +530,7 @@ interface ParsedStartBody {
   readonly flowRef?: FlowRef;
   readonly dryRun?: boolean;
   readonly correlationId?: string;
+  readonly comparison?: EvalComparison;
 }
 
 function parseStartBody(
@@ -618,6 +663,14 @@ function parseStartBody(
     };
   }
 
+  const comparison = parseComparison(b);
+  if (comparison.kind === 'err') {
+    return { kind: 'err', error: { code: 'bad-input', message: comparison.message } };
+  }
+  if (comparison.value?.versions !== undefined && agentRef !== undefined) {
+    return { kind: 'err', error: { code: 'bad-input', message: VERSIONS_NEED_A_FLOW } };
+  }
+
   return {
     kind: 'ok',
     value: {
@@ -626,6 +679,7 @@ function parseStartBody(
       ...(flowRef !== undefined && { flowRef }),
       ...(dryRun !== undefined && { dryRun }),
       ...(correlationId !== undefined && { correlationId: correlationId as string }),
+      ...(comparison.value !== undefined && { comparison: comparison.value }),
     },
   };
 }

package/src/routes/eval-versions.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * A flow candidate's `versions`, checked against the flow version when
+ * the comparison starts: each id must be an agent or tool the flow uses,
+ * at a published version. Checked once, here, before any run exists: the
+ * runs apply them as given, on resume too.
+ */
+
+import type { AgentId } from '@kindgi/agents';
+import { type FlowVersionOverrides, overridableRefs } from '@kindgi/flow';
+import type { FlowId, Semver, TenantId, ToolId } from '@kindgi/types';
+
+import type { AgentRegistryBinding } from '../agent-binding.js';
+import type { FlowRegistryBinding } from '../flow-binding.js';
+import type { ToolRegistryBinding } from '../tool-binding.js';
+
+/** Where the check reads the flow version and the agents' and tools' versions. */
+export interface FlowVersionsCheck {
+  readonly flows: FlowRegistryBinding;
+  readonly agents?: AgentRegistryBinding;
+  readonly tools?: ToolRegistryBinding;
+}
+
+export interface VersionsIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+/** A JSON Pointer token: `~` and `/` escaped. */
+const token = (id: string): string => id.replaceAll('~', '~0').replaceAll('/', '~1');
+
+async function agentIssues(
+  check: FlowVersionsCheck,
+  tenantId: TenantId,
+  label: string,
+  used: ReadonlySet<string>,
+  overrides: Readonly<Record<string, string>>,
+): Promise<VersionsIssue[]> {
+  const issues: VersionsIssue[] = [];
+  for (const [id, version] of Object.entries(overrides)) {
+    const path = `/versions/agents/${token(id)}`;
+    if (!used.has(id)) {
+      issues.push({ path, message: `flow ${label} doesn't use agent ${id}` });
+      continue;
+    }
+    const found = await check.agents?.getVersion({
+      tenantId,
+      agentId: id as AgentId,
+      version: version as Semver,
+    });
+    if (found === null) issues.push({ path, message: `agent ${id} has no version ${version}` });
+    else if (found?.unregisteredAt !== undefined) {
+      issues.push({ path, message: `agent ${id} ${version} is unregistered` });
+    }
+  }
+  return issues;
+}
+
+async function toolIssues(
+  check: FlowVersionsCheck,
+  tenantId: TenantId,
+  label: string,
+  used: ReadonlySet<string>,
+  overrides: Readonly<Record<string, string>>,
+): Promise<VersionsIssue[]> {
+  const issues: VersionsIssue[] = [];
+  for (const [id, version] of Object.entries(overrides)) {
+    const path = `/versions/tools/${token(id)}`;
+    if (!used.has(id)) {
+      issues.push({ path, message: `flow ${label} doesn't use tool ${id}` });
+      continue;
+    }
+    const found = await check.tools?.getVersion({
+      tenantId,
+      toolId: id as ToolId,
+      version: version as Semver,
+    });
+    if (found === null) issues.push({ path, message: `tool ${id} has no version ${version}` });
+  }
+  return issues;
+}
+
+/**
+ * What's wrong with a flow candidate's `versions`, one issue per id; none
+ * when they fit. Without an agent or tool registry, those versions'
+ * existence isn't checked (the runs refuse an unpublished one).
+ */
+export async function checkFlowVersions(
+  check: FlowVersionsCheck,
+  tenantId: TenantId,
+  flowRef: { readonly flowId: string; readonly version: string },
+  versions: FlowVersionOverrides,
+): Promise<readonly VersionsIssue[]> {
+  const label = `${flowRef.flowId} ${flowRef.version}`;
+  const flow = await check.flows.getVersion({
+    tenantId,
+    flowId: flowRef.flowId as FlowId,
+    version: flowRef.version,
+  });
+  if (flow === null) {
+    return [{ path: '/flowRef/version', message: `flow ${label} isn't registered` }];
+  }
+  const refs = overridableRefs(flow);
+  return [
+    ...(await agentIssues(check, tenantId, label, new Set(refs.agents), versions.agents ?? {})),
+    ...(await toolIssues(check, tenantId, label, new Set(refs.tools), versions.tools ?? {})),
+  ];
+}

package/src/routes/flows.ts

@@ -4,12 +4,17 @@
 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 { refuseWritesWhenReadOnly } from '../registry-read-only.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,9 +35,26 @@ 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>();
+  // A read-only registry (under `kindgi dev`, the pack's files) refuses
+  // every write before anything else runs.
+  r.use(
+    '*',
+    refuseWritesWhenReadOnly(() => binding.readOnly),
+  );
 
   // Authorization — mirrors agents 1:1. Check the resource directly;
   // permissions cascade from the parent project because publish writes
@@ -275,13 +297,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 +415,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 +454,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/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

@@ -0,0 +1,60 @@
+// 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;
+}
+
+/**
+ * `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 {
+    code: 'project-default-already-exists',
+    message: 'The tenant already has a Default project',
+  } as const;
+}