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

package/src/routes/eval-comparison.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { ProjectId, Semver } from '@kindgi/types';
 
 import type { EvalBaseline, EvalComparison } from '../eval-run-binding.js';
@@ -49,6 +50,34 @@ function parseBaseline(raw: unknown): EvalBaseline | string {
   return { agentId: o.agentId as AgentId, version: o.version as Semver };
 }
 
+/** `{ id: version }` with non-empty strings; an error message otherwise. */
+function versionMap(raw: unknown, name: string): Readonly<Record<string, string>> | string {
+  const o = obj(raw);
+  const valid =
+    o !== undefined &&
+    Object.entries(o).every(([id, v]) => id !== '' && typeof v === 'string' && v !== '');
+  return valid
+    ? (o as Record<string, string>)
+    : `\`${name}\` must be an object of { id: version } with non-empty strings`;
+}
+
+/** `versions: { agents?, tools? }`; `undefined` when it names nothing. */
+function parseVersions(raw: unknown): FlowVersionOverrides | undefined | string {
+  const o = obj(raw);
+  if (o === undefined) return '`versions` must be an object: { agents?, tools? }';
+  const extra = Object.keys(o).filter((key) => key !== 'agents' && key !== 'tools');
+  if (extra.length > 0) return `\`versions\` takes \`agents\` and \`tools\`, not \`${extra[0]}\``;
+  const agents = o.agents === undefined ? {} : versionMap(o.agents, 'versions.agents');
+  if (typeof agents === 'string') return agents;
+  const tools = o.tools === undefined ? {} : versionMap(o.tools, 'versions.tools');
+  if (typeof tools === 'string') return tools;
+  if (Object.keys(agents).length === 0 && Object.keys(tools).length === 0) return undefined;
+  return {
+    ...(Object.keys(agents).length > 0 && { agents }),
+    ...(Object.keys(tools).length > 0 && { tools }),
+  };
+}
+
 function integerIn(raw: unknown, name: string, max: number): number | string {
   return typeof raw === 'number' && Number.isInteger(raw) && raw >= 1 && raw <= max
     ? raw
@@ -57,8 +86,9 @@ function integerIn(raw: unknown, name: string, max: number): number | string {
 
 /**
  * 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.
+ * `reads`, `repetitions`, `k` and a flow candidate's `versions`.
+ * `undefined` when none is given (the defaults apply); an error message
+ * for a bad one.
  */
 export function parseComparison(
   b: Readonly<Record<string, unknown>>,
@@ -66,11 +96,14 @@ export function parseComparison(
   | { readonly kind: 'ok'; readonly value?: EvalComparison }
   | { readonly kind: 'err'; readonly message: string } {
   const { baseline, reads, repetitions, k } = b;
+  const versions = b.versions === undefined ? undefined : parseVersions(b.versions);
+  if (typeof versions === 'string') return { kind: 'err', message: versions };
   if (
     baseline === undefined &&
     reads === undefined &&
     repetitions === undefined &&
-    k === undefined
+    k === undefined &&
+    versions === undefined
   ) {
     return { kind: 'ok' };
   }
@@ -96,6 +129,7 @@ export function parseComparison(
       reads: reads ?? DEFAULT_COMPARISON.reads,
       repetitions: reps,
       k: topK,
+      ...(versions !== undefined && { versions }),
     },
   };
 }

package/src/routes/eval-runs.ts

@@ -17,8 +17,10 @@ import {
   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';
@@ -47,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) => {
@@ -84,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,
@@ -627,6 +667,9 @@ function parseStartBody(
   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',

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

@@ -13,6 +13,7 @@ import { statusFor, toWireError } from '../errors.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';
@@ -48,6 +49,12 @@ export function flowsRouter(
   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

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 {

package/src/routes/projects.ts

@@ -19,7 +19,11 @@ import type { Cursor, OrgId, ProjectId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
-import { projectDefaultAlreadyExistsError, slugConflictError } from './hierarchy-errors.js';
+import {
+  orgNotFoundError,
+  projectDefaultAlreadyExistsError,
+  slugConflictError,
+} from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -247,9 +251,11 @@ export function projectsRouter(
         const error =
           result.error.code === 'slug-conflict'
             ? slugConflictError('project', spec.slug)
-            : result.error.code === 'default-conflict'
-              ? projectDefaultAlreadyExistsError()
-              : { code: 'internal-server-error', message: result.error.message };
+            : result.error.code === 'org-not-found'
+              ? orgNotFoundError(result.error.orgId as unknown as string)
+              : result.error.code === 'default-conflict'
+                ? projectDefaultAlreadyExistsError()
+                : { code: 'internal-server-error', message: result.error.message };
         c.status(statusFor(error.code) as never);
         return c.json(toWireError(error, requestId));
       }
@@ -263,7 +269,9 @@ export function projectsRouter(
       const error =
         outcome.kind === 'slug-conflict'
           ? slugConflictError('project', outcome.slug)
-          : projectDefaultAlreadyExistsError();
+          : outcome.kind === 'org-not-found'
+            ? orgNotFoundError(outcome.orgId as unknown as string)
+            : projectDefaultAlreadyExistsError();
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }
@@ -596,8 +604,11 @@ export function projectsRouter(
         ),
       );
     }
-    if (outcome.kind === 'slug-conflict') {
-      const error = slugConflictError('project', outcome.slug);
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('project', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }

package/src/routes/runs.ts

@@ -685,6 +685,7 @@ function serializeRun(
     }),
     ...(row.replayOf != null && { replayOf: row.replayOf as unknown as string }),
     ...(row.evalRunId != null && { evalRunId: row.evalRunId }),
+    ...(row.versions != null && { versions: row.versions }),
   };
 }
 

package/src/routes/teams.ts

@@ -19,7 +19,7 @@ import type { Cursor, OrgId, TeamId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
-import { slugConflictError } from './hierarchy-errors.js';
+import { orgNotFoundError, slugConflictError } from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -201,7 +201,9 @@ export function teamsRouter(
         const error =
           result.error.code === 'slug-conflict'
             ? slugConflictError('team', spec.slug)
-            : { code: 'internal-server-error', message: result.error.message };
+            : result.error.code === 'org-not-found'
+              ? orgNotFoundError(result.error.orgId as unknown as string)
+              : { code: 'internal-server-error', message: result.error.message };
         c.status(statusFor(error.code) as never);
         return c.json(toWireError(error, requestId));
       }
@@ -209,8 +211,11 @@ export function teamsRouter(
       return c.json({ id: result.value.teamId as unknown as string });
     }
     const outcome = await binding.create(tenantId, spec);
-    if (outcome.kind === 'slug-conflict') {
-      const error = slugConflictError('team', outcome.slug);
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('team', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }
@@ -542,8 +547,11 @@ export function teamsRouter(
         ),
       );
     }
-    if (outcome.kind === 'slug-conflict') {
-      const error = slugConflictError('team', outcome.slug);
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('team', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }

package/src/routes/tools.ts

@@ -9,6 +9,7 @@ import type { Cursor, ProjectId, TenantId, ToolId, UserId } from '@kindgi/types'
 
 import { statusFor, toWireError } from '../errors.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';
@@ -47,6 +48,12 @@ export function toolsRouter(
   onWrite?: ToolWriteHook,
 ): 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 `tool#parent@project`
   // written in-tx by publish; direct check via `ref('tool', businessId)`.

package/src/tool-binding.ts

@@ -6,6 +6,8 @@ import type { Scope } from '@kindgi/platform';
 import type { ToolManifest } from '@kindgi/tools';
 import type { Cursor, ProjectId, Semver, TenantId, ToolId } from '@kindgi/types';
 
+import type { RegistryReadOnly } from './registry-read-only.js';
+
 /**
  * Caller-plugged surface for the tool catalog. Versioned CRUD mirroring
  * `AgentRegistryBinding` — the API package does NOT own registry
@@ -30,6 +32,13 @@ import type { Cursor, ProjectId, Semver, TenantId, ToolId } from '@kindgi/types'
  * not-found via `headExists`).
  */
 export interface ToolRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its tools): every write is refused
+   * with `409 registry-read-only` and this reason, before the binding is
+   * called. See `RegistryReadOnly`.
+   */
+  readonly readOnly?: RegistryReadOnly;
   /**
    * Cursor-paginated list of tools (latest active version per id).
    * Optional `nameFilter` is a prefix match on the tool id — tools use