@kindgi/api 0.1.3 → 0.1.4-rc.0

package/src/routes/deployments.ts

@@ -5,9 +5,10 @@ import { createHash } from 'node:crypto';
 
 import { Hono } from 'hono';
 
-import type { AgentId } from '@kindgi/agents';
+import type { Agent, AgentId, AgentPins } from '@kindgi/agents';
 import { tuplesForCreate } from '@kindgi/authz';
 import { parsePublicKeyPem, verifyEd25519 } from '@kindgi/crypto';
+import type { Flow, FlowPins } from '@kindgi/flow';
 import { type Guardrail, validateGuardrailSpec } from '@kindgi/guardrails';
 import type { ProjectBinding, Scope } from '@kindgi/platform';
 import { validateToolManifest } from '@kindgi/tools';
@@ -16,13 +17,20 @@ import type {
   FlowId,
   GuardrailId,
   ProjectId,
+  Semver,
   SigningKeyId,
   TenantId,
   ToolId,
 } from '@kindgi/types';
 
 import type { AgentRegistryBinding } from '../agent-binding.js';
+import { type UnpinnableRef, publishDeployedAgent, resolveAgentPins } from '../agent-pins.js';
+import type { BlockRegistryBinding } from '../block-binding.js';
+import type { DeployedVersionOutcome } from '../deploy-versions.js';
 import type {
+  DeployedAgent,
+  DeployedFlow,
+  DeployedVersion,
   Deployment,
   DeploymentBinding,
   DeploymentPrimitiveCounts,
@@ -30,6 +38,7 @@ import type {
 } from '../deployment-binding.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { FlowRegistryBinding } from '../flow-binding.js';
+import { publishDeployedFlow, resolveFlowPins } from '../flow-pins.js';
 import type { GuardrailRegistryBinding } from '../guardrail-binding.js';
 import type { ImageRegistryBinding } from '../image-registry-binding.js';
 import type { SecretBinding } from '../secrets-binding.js';
@@ -112,6 +121,8 @@ export interface DeploymentsRouterBindings {
   readonly guardrailRegistry?: GuardrailRegistryBinding;
   readonly agentRegistry?: AgentRegistryBinding;
   readonly flowRegistry?: FlowRegistryBinding;
+  /** Data blocks: an agent's block references are pinned at deploy with its tools. */
+  readonly blockRegistry?: BlockRegistryBinding;
   /**
    * REQUIRED at runtime for `POST /v1/deployments/:deploymentId/secrets`.
    * Optional at the type level so app compositions without a secrets
@@ -529,6 +540,10 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
     }
 
     const rolled: RollbackAction[] = [];
+    // The version each agent is registered under: its definition's, or
+    // the one a deploy registered in its place (`publishDeployedAgent`).
+    const deployedAgents: DeployedAgent[] = [];
+    const deployedFlows: DeployedFlow[] = [];
     try {
       if (bindings.toolRegistry !== undefined && defaultProjectId !== undefined) {
         for (const tool of validated.tools) {
@@ -578,58 +593,50 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
         }
       }
       if (bindings.agentRegistry !== undefined && defaultProjectId !== undefined) {
-        for (const agent of validated.agents) {
-          const projectIdForAgent = defaultProjectId;
-          const outcome = await bindings.agentRegistry.publish({
+        deployedAgents.push(
+          ...(await registerAgents({
+            agents: bindings.agentRegistry,
+            tools: bindings.toolRegistry,
+            blocks: bindings.blockRegistry,
             tenantId,
-            projectId: projectIdForAgent,
-            agent,
-            // Signed deploys have no per-request principal — pass parent-
-            // only tuples (no owner grant). Tenant admins keep access via
-            // `admin from parent` cascade.
-            enqueueTuples: (agentId) =>
-              tuplesForCreate({
-                kind: 'agent',
-                id: agentId as AgentId,
-                tenantId,
-                projectId: projectIdForAgent,
-              }),
-          });
-          if (outcome.kind === 'ok') {
-            const agentId = outcome.agentId;
-            const version = outcome.version;
-            rolled.push(async () => {
-              await bindings.agentRegistry?.unregister({ tenantId, agentId, version });
-            });
-          }
-        }
+            projectId: defaultProjectId,
+            defined: validated.agents,
+            rolled,
+          })),
+        );
+      } else {
+        deployedAgents.push(...validated.agents.map(deployedPrimitive));
       }
       if (bindings.flowRegistry !== undefined && defaultProjectId !== undefined) {
-        for (const flow of validated.flows) {
-          const projectIdForGraph = defaultProjectId;
-          const outcome = await bindings.flowRegistry.publish({
+        deployedFlows.push(
+          ...(await registerFlows({
+            flows: bindings.flowRegistry,
+            tools: bindings.toolRegistry,
+            agents: bindings.agentRegistry,
             tenantId,
-            projectId: projectIdForGraph,
-            flow,
-            enqueueTuples: (flowId) =>
-              tuplesForCreate({
-                kind: 'flow',
-                id: flowId as FlowId,
-                tenantId,
-                projectId: projectIdForGraph,
-              }),
-          });
-          if (outcome.kind === 'ok') {
-            const flowId = outcome.flowId;
-            const version = outcome.version;
-            rolled.push(async () => {
-              await bindings.flowRegistry?.unregister({ tenantId, flowId, version });
-            });
-          }
-        }
+            projectId: defaultProjectId,
+            defined: validated.flows,
+            rolled,
+          })),
+        );
+      } else {
+        deployedFlows.push(...validated.flows.map(deployedPrimitive));
       }
     } catch (cause) {
       await rollback(rolled);
+      if (cause instanceof UnpinnableDeploy) {
+        c.status(statusFor('invalid-agent') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'validation-failed',
+              message: `The deployment's agents or flows use tool or agent versions that aren't published (${cause.issues.length} issue${cause.issues.length === 1 ? '' : 's'}); nothing was deployed`,
+              issues: cause.issues as unknown as Record<string, unknown>[],
+            },
+            requestId,
+          ),
+        );
+      }
       c.status(statusFor('internal-server-error') as never);
       return c.json(
         toWireError(
@@ -669,14 +676,8 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             version: t.version,
           })),
           guardrails: validated.guardrails.map((g) => ({ id: g.id as unknown as string })),
-          agents: validated.agents.map((a) => ({
-            id: a.id as unknown as string,
-            version: a.version as unknown as string,
-          })),
-          flows: validated.flows.map((f) => ({
-            id: f.id as unknown as string,
-            version: f.version as unknown as string,
-          })),
+          agents: deployedAgents,
+          flows: deployedFlows,
         },
       });
     } catch (cause) {
@@ -1374,8 +1375,18 @@ function validateAgentIndexShape(
   if (typeof spec.name !== 'string' || (spec.name as string).length === 0) {
     out.push({ path: '/name', message: 'agent.name must be a non-empty string' });
   }
-  if (typeof spec.instructions !== 'string' || (spec.instructions as string).length === 0) {
-    out.push({ path: '/instructions', message: 'agent.instructions must be a non-empty string' });
+  const instructions = spec.instructions as { prompt?: unknown; version?: unknown } | string;
+  const promptRef =
+    typeof instructions === 'object' &&
+    instructions !== null &&
+    typeof instructions.prompt === 'string' &&
+    typeof instructions.version === 'string';
+  if (!promptRef && (typeof instructions !== 'string' || instructions.length === 0)) {
+    out.push({
+      path: '/instructions',
+      message:
+        'agent.instructions must be a non-empty string, or a prompt block { prompt, version }',
+    });
   }
   if (!Array.isArray(spec.capabilities)) {
     out.push({ path: '/capabilities', message: 'agent.capabilities must be an array' });
@@ -1411,6 +1422,205 @@ function validateFlowIndexShape(
 
 type RollbackAction = () => Promise<void>;
 
+/** A deploy whose agents or flows use a tool or agent with no published version in range. */
+class UnpinnableDeploy extends Error {
+  constructor(readonly issues: readonly UnpinnableRef[]) {
+    super('the deployment uses tools or agents that are not published');
+  }
+}
+
+/** A deployed agent or flow registered under its definition's version. */
+function deployedPrimitive(definition: { readonly id: string; readonly version: string }): {
+  id: string;
+  version: string;
+} {
+  return { id: definition.id, version: definition.version };
+}
+
+/** A deployed agent or flow, under the version the deploy rule registered it as. */
+function deployedVersion(
+  definition: { readonly id: string; readonly version: string },
+  outcome: DeployedVersionOutcome,
+): DeployedVersion {
+  return outcome.kind === 'reused' || outcome.kind === 'renumbered'
+    ? {
+        id: definition.id,
+        version: outcome.version,
+        authoredVersion: definition.version,
+        reason: outcome.reason,
+        newVersion: outcome.kind === 'renumbered',
+        ...(outcome.pinChanges !== undefined && { pinChanges: outcome.pinChanges }),
+      }
+    : deployedPrimitive(definition);
+}
+
+/**
+ * Register a deployment's agents, each under the version it's registered
+ * as (`DeployedAgent`), pushing a rollback for each version it writes.
+ *
+ * With a tool registry, every agent is pinned first (the pack's tools
+ * are registered by now): one whose range matches no published version
+ * throws `UnpinnableDeploy` before any agent is written, and the deploy
+ * rolls back. Each is then registered by `publishDeployedAgent`, which
+ * never keeps a version's old pins. Without one, agents register
+ * unpinned, as before pins existed.
+ */
+async function registerAgents(input: {
+  readonly agents: AgentRegistryBinding;
+  readonly tools: ToolRegistryBinding | undefined;
+  readonly blocks: BlockRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly defined: readonly Agent[];
+  readonly rolled: RollbackAction[];
+}): Promise<DeployedAgent[]> {
+  const { agents, tools, blocks, tenantId, projectId, rolled } = input;
+  // Signed deploys have no per-request principal — pass parent-only
+  // tuples (no owner grant). Tenant admins keep access via
+  // `admin from parent` cascade.
+  const enqueueTuples = (agentId: string) =>
+    tuplesForCreate({ kind: 'agent', id: agentId as AgentId, tenantId, projectId });
+  const written = (agentId: AgentId, version: Semver) =>
+    rolled.push(async () => {
+      await agents.unregister({ tenantId, agentId, version });
+    });
+
+  if (tools === undefined) {
+    for (const agent of input.defined) {
+      const outcome = await agents.publish({ tenantId, projectId, agent, enqueueTuples });
+      if (outcome.kind === 'ok') written(outcome.agentId, outcome.version);
+    }
+    return input.defined.map(deployedPrimitive);
+  }
+
+  const pinsOf = await pinAgents(tools, blocks, tenantId, input.defined);
+  const deployed: DeployedAgent[] = [];
+  for (const [i, agent] of input.defined.entries()) {
+    const pins = pinsOf[i] as AgentPins;
+    const outcome = await publishDeployedAgent({
+      agents,
+      tenantId,
+      projectId,
+      agent,
+      pins,
+      enqueueTuples,
+    });
+    if (outcome.kind === 'registered' || outcome.kind === 'renumbered') {
+      written(agent.id, outcome.version as unknown as Semver);
+    }
+    deployed.push(deployedVersion(agent, outcome));
+  }
+  return deployed;
+}
+
+/**
+ * Register a deployment's flows, each under the version it's registered
+ * as, pushing a rollback for each version it writes. Runs after the
+ * agents, so a flow's agent pins see the versions this deploy
+ * registered: a tool change cascades through an agent into a flow
+ * within the one deploy, each derived once.
+ *
+ * With the tool and agent registries, every flow is pinned first; one
+ * that runs a tool or agent with no published version throws
+ * `UnpinnableDeploy` before any flow is written, and the deploy rolls
+ * back. Without them, flows register unpinned, as before pins existed.
+ */
+async function registerFlows(input: {
+  readonly flows: FlowRegistryBinding;
+  readonly tools: ToolRegistryBinding | undefined;
+  readonly agents: AgentRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly defined: readonly Flow[];
+  readonly rolled: RollbackAction[];
+}): Promise<DeployedFlow[]> {
+  const { flows, tools, agents, tenantId, projectId, rolled } = input;
+  const enqueueTuples = (flowId: string) =>
+    tuplesForCreate({ kind: 'flow', id: flowId as FlowId, tenantId, projectId });
+  const written = (flowId: FlowId, version: string) =>
+    rolled.push(async () => {
+      await flows.unregister({ tenantId, flowId, version: version as never });
+    });
+
+  if (tools === undefined || agents === undefined) {
+    for (const flow of input.defined) {
+      const outcome = await flows.publish({ tenantId, projectId, flow, enqueueTuples });
+      if (outcome.kind === 'ok') written(outcome.flowId, outcome.version as unknown as string);
+    }
+    return input.defined.map(deployedPrimitive);
+  }
+
+  const pinsOf = await pinFlows(tools, agents, tenantId, input.defined);
+  const deployed: DeployedFlow[] = [];
+  for (const [i, flow] of input.defined.entries()) {
+    const outcome = await publishDeployedFlow({
+      flows,
+      tenantId,
+      projectId,
+      flow,
+      pins: pinsOf[i] as FlowPins,
+      enqueueTuples,
+    });
+    if (outcome.kind === 'registered' || outcome.kind === 'renumbered') {
+      written(flow.id, outcome.version);
+    }
+    deployed.push(deployedVersion(flow, outcome));
+  }
+  return deployed;
+}
+
+/** Each flow's pins, in order; throws `UnpinnableDeploy` naming every tool or agent with no published version. */
+async function pinFlows(
+  tools: ToolRegistryBinding,
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  defined: readonly Flow[],
+): Promise<FlowPins[]> {
+  const pins: FlowPins[] = [];
+  const unpinnable: UnpinnableRef[] = [];
+  for (const [i, flow] of defined.entries()) {
+    const resolved = await resolveFlowPins(tools, agents, tenantId, flow);
+    if (resolved.kind === 'ok') {
+      pins.push(resolved.pins);
+      continue;
+    }
+    for (const issue of resolved.issues) {
+      unpinnable.push({
+        path: `/flows/${i}${issue.path}`,
+        message: `flow "${flow.id as unknown as string}": ${issue.message}`,
+      });
+    }
+  }
+  if (unpinnable.length > 0) throw new UnpinnableDeploy(unpinnable);
+  return pins;
+}
+
+/** Each agent's pins, in order; throws `UnpinnableDeploy` naming every range that matches nothing. */
+async function pinAgents(
+  tools: ToolRegistryBinding,
+  blocks: BlockRegistryBinding | undefined,
+  tenantId: TenantId,
+  defined: readonly Agent[],
+): Promise<AgentPins[]> {
+  const pins: AgentPins[] = [];
+  const unpinnable: UnpinnableRef[] = [];
+  for (const [i, agent] of defined.entries()) {
+    const resolved = await resolveAgentPins(tools, tenantId, agent, blocks);
+    if (resolved.kind === 'ok') {
+      pins.push(resolved.pins);
+      continue;
+    }
+    for (const issue of resolved.issues) {
+      unpinnable.push({
+        path: `/agents/${i}${issue.path}`,
+        message: `agent "${agent.id as unknown as string}": ${issue.message}`,
+      });
+    }
+  }
+  if (unpinnable.length > 0) throw new UnpinnableDeploy(unpinnable);
+  return pins;
+}
+
 async function rollback(actions: readonly RollbackAction[]): Promise<void> {
   // Reverse order — last-in, first-out — so registrations are undone in
   // the mirror sequence of their creation.

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 }),
   };
 }