@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/derive-agent-version.ts

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import {
+  type Agent,
+  type AgentId,
+  type AgentPins,
+  MODEL_SETTINGS_SCHEMA,
+  pinsDigest,
+  settingsSchemaIssues,
+} from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import { latestVersion, nextVersion } from '@kindgi/tools';
+import type { ProjectId, Semver, TenantId } from '@kindgi/types';
+
+import type { AgentRegistryBinding, AgentVersionRecord } from './agent-binding.js';
+import { activeAgentVersions } from './agent-pins.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+
+/** Which data-block pins to swap, by kind then block id → exact version. */
+export interface PinSwaps {
+  readonly prompts?: Readonly<Record<string, string>>;
+  readonly settings?: Readonly<Record<string, string>>;
+}
+
+export interface DeriveAgentVersionInput {
+  readonly agents: AgentRegistryBinding;
+  readonly blocks: BlockRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  /** The version to derive from: it must be pinned. */
+  readonly from: string;
+  readonly swaps: PinSwaps;
+  /** A short label for the new version. */
+  readonly label?: string;
+  /** Who derived it (`user:<id>`). */
+  readonly by?: string;
+  /** The project, when the store doesn't record one on the version. */
+  readonly projectId?: ProjectId;
+  /** The authorization tuples for the new version, in the project it lands in. */
+  readonly tuplesFor: (projectId: ProjectId) => TupleEnqueueHook;
+}
+
+export interface SwapIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+export type DeriveAgentVersionOutcome =
+  | { readonly kind: 'ok'; readonly agent: Agent }
+  | { readonly kind: 'not-found' }
+  | { readonly kind: 'unpinned' }
+  | { readonly kind: 'invalid'; readonly issues: readonly SwapIssue[] }
+  | { readonly kind: 'no-project' }
+  | { readonly kind: 'project-not-found'; readonly projectId: ProjectId };
+
+/** How many numbers after the highest a derive tries before it gives up. */
+const MAX_TRIES = 100;
+
+/**
+ * Derive a new agent version from a pinned one with some data-block
+ * pins swapped: an expert's edit (a new prompt or settings version)
+ * reaching an agent without a code change. The new version is the old
+ * one's bag with those pins swapped (`derivedFrom: { version, reason:
+ * 'edited', label, by }`), numbered the next free patch after the
+ * agent's highest version (versions never change).
+ *
+ * Only data-block pins swap: a swap must name a block the version
+ * already references (adding one is a code change), at a published,
+ * active version of the right kind (and, for the model-settings block,
+ * model settings). Tool pins come from code.
+ */
+export async function deriveAgentVersion(
+  input: DeriveAgentVersionInput,
+): Promise<DeriveAgentVersionOutcome> {
+  const { agents, tenantId, agentId } = input;
+  const from = await agents.getVersion({ tenantId, agentId, version: input.from as Semver });
+  if (from === null) return { kind: 'not-found' };
+  if (from.pins === undefined) return { kind: 'unpinned' };
+
+  const issues = await swapIssues(input, from, from.pins);
+  if (issues.length > 0) return { kind: 'invalid', issues };
+  const pins: AgentPins = {
+    tools: from.pins.tools,
+    prompts: { ...from.pins.prompts, ...(input.swaps.prompts ?? {}) },
+    settings: { ...from.pins.settings, ...(input.swaps.settings ?? {}) },
+  };
+  const digest = pinsDigest(pins);
+  if (digest === from.pinsDigest) {
+    return { kind: 'invalid', issues: [{ path: '/pins', message: 'no pin changes' }] };
+  }
+
+  const projectId = from.projectId ?? input.projectId;
+  if (projectId === undefined) return { kind: 'no-project' };
+  const { unregisteredAt: _u, projectId: _p, derivedFrom: _d, ...definition } = from;
+  return publishNextFree(input, projectId, {
+    ...definition,
+    pins,
+    pinsDigest: digest,
+    derivedFrom: {
+      version: from.version,
+      reason: 'edited',
+      ...(input.label !== undefined && { label: input.label }),
+      ...(input.by !== undefined && { by: input.by }),
+    },
+  });
+}
+
+/** Publish the derived version under the first free patch after the agent's highest. */
+async function publishNextFree(
+  input: DeriveAgentVersionInput,
+  projectId: ProjectId,
+  derived: Agent,
+): Promise<DeriveAgentVersionOutcome> {
+  const { agents, tenantId, agentId } = input;
+  const active = await activeAgentVersions(agents, tenantId, agentId);
+  const highest =
+    latestVersion(active.map((a) => a.version as unknown as string)) ??
+    (derived.version as unknown as string);
+  let candidate = nextVersion(highest);
+  for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+    const agent: Agent = { ...derived, version: candidate as Semver };
+    const outcome = await agents.publish({
+      tenantId,
+      projectId,
+      agent,
+      enqueueTuples: input.tuplesFor(projectId),
+    });
+    if (outcome.kind === 'ok') return { kind: 'ok', agent };
+    if (outcome.kind === 'project-not-found') return { kind: 'project-not-found', projectId };
+    candidate = nextVersion(candidate);
+  }
+  throw new Error(`agent "${agentId as unknown as string}": no free version after ${highest}`);
+}
+
+/** What's wrong with the swaps, against the version's references and the block store. */
+async function swapIssues(
+  input: DeriveAgentVersionInput,
+  from: AgentVersionRecord,
+  pins: AgentPins,
+): Promise<SwapIssue[]> {
+  const issues: SwapIssue[] = [];
+  const swaps = [
+    ...Object.entries(input.swaps.prompts ?? {}).map(([id, v]) => ['prompts', id, v] as const),
+    ...Object.entries(input.swaps.settings ?? {}).map(([id, v]) => ['settings', id, v] as const),
+  ];
+  if (swaps.length === 0)
+    return [{ path: '/pins', message: 'name at least one prompt or settings pin to swap' }];
+  for (const [kind, id, version] of swaps) {
+    const path = `/pins/${kind}/${id}`;
+    if (pins[kind][id] === undefined) {
+      issues.push({
+        path,
+        message: `agent version ${from.version} doesn't reference ${kind === 'prompts' ? 'prompt' : 'settings'} block "${id}"; adding a block is a code change`,
+      });
+      continue;
+    }
+    const problem = await blockProblem(input, from, kind, id, version);
+    if (problem !== undefined) issues.push({ path, message: problem });
+  }
+  return issues;
+}
+
+async function blockProblem(
+  input: DeriveAgentVersionInput,
+  from: AgentVersionRecord,
+  kind: 'prompts' | 'settings',
+  id: string,
+  version: string,
+): Promise<string | undefined> {
+  if (input.blocks === undefined) return 'this runtime serves no data blocks';
+  const block = await input.blocks.getVersion({ tenantId: input.tenantId, blockId: id, version });
+  const what = `block "${id}" version ${version}`;
+  if (block === null) return `${what} isn't published`;
+  if (block.unregisteredAt !== undefined) return `${what} is unregistered`;
+  const wanted = kind === 'prompts' ? 'prompt' : 'settings';
+  if (block.kind !== wanted) return `${what} is a ${block.kind} block, not ${wanted}`;
+  if (block.kind === 'settings' && from.modelSettings?.id === id) {
+    const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+    if (issues.length > 0) {
+      return `${what} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The first version after `after` that no version of the agent holds,
+ * active or unregistered (versions never change): what a refused
+ * publish of a taken number suggests, by the deploy rule's numbering.
+ * `undefined` when none is free within the tries.
+ */
+export async function nextFreeAgentVersion(
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  agentId: AgentId,
+  after: string,
+): Promise<string | undefined> {
+  let candidate = nextVersion(after);
+  for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+    const held = await agents.getVersion({ tenantId, agentId, version: candidate as Semver });
+    if (held === null) return candidate;
+    candidate = nextVersion(candidate);
+  }
+  return undefined;
+}

package/src/errors.ts

@@ -31,6 +31,7 @@ export interface WireError {
 export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   // 400 — bad request
   'validation-failed': 400,
+  'kind-not-applied': 400,
   'unknown-field': 400,
   'bad-input': 400,
   'unresolved-tool': 400,
@@ -160,10 +161,22 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'policy-not-found': 404,
   'policy-already-registered': 409,
   // Admin plane — eval suites.
+  'block-not-found': 404,
+  'block-already-registered': 409,
+  'block-project-mismatch': 409,
   'eval-suite-not-found': 404,
   'eval-suite-already-registered': 409,
   // Admin plane — eval-run dispatch.
   'eval-run-not-found': 404,
+  // Judgments (yes/no on a run's output items) and judge classes.
+  'judgment-not-found': 404,
+  'judge-class-not-found': 404,
+  'judge-class-name-taken': 409,
+  'judge-class-not-applicable': 400,
+  'run-not-finished': 409,
+  'item-not-found': 400,
+  // The judgment binding can't list judged runs, so no test sets from judgments.
+  'test-sets-not-supported': 501,
   'eval-run-already-terminal': 409,
   'dispatcher-not-registered': 422,
   'dispatcher-input-invalid': 400,
@@ -215,6 +228,10 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'project-not-found': 404,
   'team-membership-not-found': 404,
   'project-membership-not-found': 404,
+  // A slug another org, team or project in the tenant already has; a
+  // second Default project.
+  'slug-conflict': 409,
+  'project-default-already-exists': 409,
   'tenant-not-found': 404,
   'tenant-config-not-found': 404,
   'tenant-config-revision-conflict': 409,

package/src/eval-case-binding.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import type { JudgedItem, JudgedRunContext, JudgedSubject } from './judgment-binding.js';
+
+/**
+ * Caller-plugged storage for the cases of an eval-suite version, kept
+ * apart from the version's `spec` because a set can hold hundreds of
+ * cases. A `judged` suite version's cases are built from judgments: each
+ * is a copy of one judged run (its input, what it read, the output that
+ * was judged) with the judgments of its items summed up. Copies, so a
+ * test set stays the same when judgments are removed or runs purged.
+ *
+ * Cases are written once, when the version is published, and removed
+ * with it.
+ */
+export interface EvalCaseStoreBinding {
+  /** Store a version's cases. Called once, right after the version is published. */
+  putCases(input: EvalCasePutInput): Promise<void>;
+  /** A version's cases, in the order they were stored, cursor-paginated. */
+  listCases(input: EvalCaseListInput): Promise<EvalCasePage>;
+}
+
+/** The judgments of one item of a case's output, summed up. */
+export interface JudgedItemSummary extends JudgedItem {
+  readonly yes: number;
+  readonly no: number;
+  /** The weight behind "yes" (an unclassified judgment counts 1). */
+  readonly yesWeight: number;
+  /** The weight behind all judgments of the item. */
+  readonly totalWeight: number;
+  /** The reasons given, newest first. */
+  readonly reasons: readonly { readonly verdict: 'yes' | 'no'; readonly reason: string }[];
+}
+
+/** One case of a `judged` suite: a copy of a judged run and what people said about it. */
+export interface JudgedEvalCase {
+  /** The judged run's id. */
+  readonly caseId: string;
+  /** What ran: the agent or flow at a version (the baseline when comparing to the recording). */
+  readonly subject: JudgedSubject;
+  readonly input: unknown;
+  /** What the turn read besides its input; absent when it wasn't captured. */
+  readonly context?: JudgedRunContext;
+  /** The output that was judged. */
+  readonly output: unknown;
+  readonly items: readonly JudgedItemSummary[];
+}
+
+export interface EvalCasePutInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+  readonly cases: readonly JudgedEvalCase[];
+}
+
+export interface EvalCaseListInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+  readonly cursor?: Cursor;
+  readonly limit: number;
+}
+
+export interface EvalCasePage {
+  readonly data: readonly JudgedEvalCase[];
+  readonly hasMore: boolean;
+  readonly nextCursor?: Cursor;
+}

package/src/eval-run-binding.ts

@@ -105,6 +105,8 @@ export interface EvalRun {
   readonly result?: Readonly<Record<string, unknown>>;
   readonly error?: string;
   readonly correlationId?: string;
+  /** A comparison eval run's baseline, reads and repetitions. */
+  readonly comparison?: EvalComparison;
 }
 
 export interface EvalRunFilter {
@@ -116,6 +118,35 @@ export interface EvalRunFilter {
   readonly to?: Timestamp;
 }
 
+/**
+ * What a comparison eval run compares the candidate against:
+ *   - `'recorded'`: the output each case recorded (what was judged);
+ *   - `{ agentId, version }`: that version, replayed under the same rules;
+ *   - `{ live }`: the version live in a scope (a project, segments).
+ */
+export type EvalBaseline =
+  | 'recorded'
+  | { readonly agentId: AgentId; readonly version: Semver }
+  | {
+      readonly live: {
+        readonly projectId?: ProjectId;
+        readonly segments?: Readonly<Record<string, string>>;
+      };
+    };
+
+/** Whether replayed reads use the past run's results when it has them, or run live. */
+export type EvalReads = 'recorded' | 'live';
+
+/** How a comparison eval run runs its cases (absent: the run isn't a comparison). */
+export interface EvalComparison {
+  readonly baseline: EvalBaseline;
+  readonly reads: EvalReads;
+  /** How many times each case runs (1–10); with more than 1, the summary shows the spread. */
+  readonly repetitions: number;
+  /** How many ranked items `weightedPrecisionAtK` looks at (1–100). */
+  readonly k: number;
+}
+
 export interface EvalRunStartInput {
   readonly tenantId: TenantId;
   /**
@@ -130,6 +161,8 @@ export interface EvalRunStartInput {
   readonly flowRef?: FlowRef;
   readonly dryRun?: boolean;
   readonly correlationId?: string;
+  /** Set for a comparison eval run (a `judged` suite): its baseline, reads and repetitions. */
+  readonly comparison?: EvalComparison;
 }
 
 /**

package/src/eval-run-dispatcher.ts

@@ -3,10 +3,13 @@
 
 import { randomUUID } from 'node:crypto';
 
-import type { RunId, TenantId, Timestamp } from '@kindgi/types';
+import type { ReplayTurnReport } from '@kindgi/agents';
+import type { RunReplayRef } from '@kindgi/runtime';
+import type { ProjectId, RunId, TenantId, Timestamp } from '@kindgi/types';
 
 import type {
   AgentRef,
+  EvalComparison,
   EvalRun,
   EvalRunBinding,
   EvalRunCancelInput,
@@ -50,6 +53,16 @@ export interface EvalRunSubjectInvokeInput {
   readonly input: unknown;
   readonly dryRun: boolean;
   readonly abortSignal: AbortSignal;
+  /** The eval run's project: where the subject runs. */
+  readonly projectId?: ProjectId;
+  /**
+   * Set when the subject re-runs a past run (a comparison eval run): the
+   * run is a replay of `of` for the eval run, under the replay rules
+   * (`InvokeAgentInput.replay`).
+   */
+  readonly replay?: RunReplayRef;
+  /** The conversation before the past turn, oldest first: a replayed turn starts from it. */
+  readonly history?: readonly unknown[];
 }
 
 export interface EvalRunSubjectInvokeOutcome {
@@ -57,6 +70,22 @@ export interface EvalRunSubjectInvokeOutcome {
   readonly error?: string;
   readonly costUsd?: number;
   readonly durationMs?: number;
+  /** The run the subject ran in. */
+  readonly runId?: RunId;
+  /** A replay's report: each tool call and what happened to it (`AgentTurnResult.replay`). */
+  readonly replay?: ReplayTurnReport;
+  /** The provider and model that answered. */
+  readonly provider?: { readonly id: string; readonly model: string };
+  /**
+   * Set when a replayed flow stopped at a tool call the replay refused (a
+   * write the past run didn't make): no output, and what it would have
+   * done. Not an error: the replay did what it's meant to.
+   */
+  readonly stopped?: {
+    readonly toolId: string;
+    readonly arguments: unknown;
+    readonly reason?: string;
+  };
 }
 
 /**
@@ -100,6 +129,10 @@ export interface DispatchContext {
   readonly dryRun: boolean;
   readonly abortSignal: AbortSignal;
   readonly subject: EvalSubjectInvoker;
+  /** The eval run's project. */
+  readonly projectId?: ProjectId;
+  /** A comparison eval run's baseline, reads and repetitions. */
+  readonly comparison?: EvalComparison;
   onProgress(perCase: Readonly<Record<string, unknown>>): void;
 }
 
@@ -113,6 +146,7 @@ export interface EvalRunDispatcher {
   validate?(
     suite: EvalSuite,
     target: AgentRef | FlowRef,
+    comparison?: EvalComparison,
   ): { kind: 'ok' } | { kind: 'err'; message: string };
   dispatch(ctx: DispatchContext): Promise<DispatchResult>;
 }
@@ -311,26 +345,13 @@ export function createInProcessEvalRunBinding(
         };
       }
       if (dispatcher.validate !== undefined) {
-        const v = dispatcher.validate(suite, target);
+        const v = dispatcher.validate(suite, target, input.comparison);
         if (v.kind === 'err') {
           return { kind: 'dispatcher-input-invalid', message: v.message };
         }
       }
       const runId = randomUUID() as unknown as RunId;
-      const startedAt = now().toISOString() as unknown as Timestamp;
-      const record: EvalRun = {
-        runId,
-        tenantId: input.tenantId,
-        suiteId: suite.id,
-        suiteVersion: suite.version,
-        kind: suite.kind,
-        ...(input.agentRef !== undefined && { agentRef: input.agentRef }),
-        ...(input.flowRef !== undefined && { flowRef: input.flowRef }),
-        status: 'running' as EvalRunStatus,
-        dryRun: input.dryRun === true,
-        startedAt,
-        ...(input.correlationId !== undefined && { correlationId: input.correlationId }),
-      };
+      const record = newRunRecord(input, suite, runId, now());
       setRun(record);
       const controller = new AbortController();
       controllers.set(runId as unknown as string, controller);
@@ -349,6 +370,8 @@ export function createInProcessEvalRunBinding(
             dryRun: input.dryRun === true,
             abortSignal: controller.signal,
             subject: options.subject,
+            projectId: input.projectId,
+            ...(input.comparison !== undefined && { comparison: input.comparison }),
             onProgress: (perCaseEntry: Readonly<Record<string, unknown>>) => {
               const current = runs.get(runId as unknown as string);
               if (current === undefined) return;
@@ -489,6 +512,24 @@ export function createInProcessEvalRunBinding(
   };
 }
 
+/** A started run's row: `running`, with what it runs and how. */
+function newRunRecord(input: EvalRunStartInput, suite: EvalSuite, runId: RunId, at: Date): EvalRun {
+  return {
+    runId,
+    tenantId: input.tenantId,
+    suiteId: suite.id,
+    suiteVersion: suite.version,
+    kind: suite.kind,
+    ...(input.agentRef !== undefined && { agentRef: input.agentRef }),
+    ...(input.flowRef !== undefined && { flowRef: input.flowRef }),
+    status: 'running',
+    dryRun: input.dryRun === true,
+    startedAt: at.toISOString() as unknown as Timestamp,
+    ...(input.correlationId !== undefined && { correlationId: input.correlationId }),
+    ...(input.comparison !== undefined && { comparison: input.comparison }),
+  };
+}
+
 function isTerminal(status: EvalRunStatus): boolean {
   return status === 'completed' || status === 'failed' || status === 'cancelled';
 }

package/src/eval-suite-binding.ts

@@ -100,6 +100,8 @@ export const EVAL_KINDS = [
   'human-review',
   'benchmark',
   'custom',
+  /** Built from judgments of past runs: cases are copies of judged runs (`EvalCaseStoreBinding`). */
+  'judged',
 ] as const;
 export type EvalKind = (typeof EVAL_KINDS)[number];
 

package/src/flow-binding.ts

@@ -39,11 +39,12 @@ export interface FlowRegistryBinding {
    */
   get(input: FlowGetInput): Promise<Flow | null>;
   /**
-   * Specific `(flowId, version)` lookup, or `null` if unknown.
-   * Returns tombstoned versions too — provenance paths need to
-   * resolve historical run references.
+   * Specific `(flowId, version)` lookup, or `null` if unknown. Returns
+   * unregistered (tombstoned) versions too, with `unregisteredAt` set:
+   * a resumed run and provenance read them, while a new run that names
+   * one is refused.
    */
-  getVersion(input: FlowGetVersionInput): Promise<Flow | null>;
+  getVersion(input: FlowGetVersionInput): Promise<FlowVersionRecord | null>;
   /**
    * Head-row existence check. Lets `GET /v1/flows/{id}` distinguish
    * `410 gone` (identity exists, no active version) from `404 not-
@@ -79,6 +80,12 @@ export interface FlowRegistryBinding {
   reinstateVersion(input: FlowReinstateVersionInput): Promise<FlowReinstateVersionOutcome>;
 }
 
+/** A flow version as `getVersion` reads it: `unregisteredAt` is set when it's unregistered. */
+export type FlowVersionRecord = Flow & {
+  /** ISO-8601; present only on an unregistered version. */
+  readonly unregisteredAt?: string;
+};
+
 export interface FlowListInput {
   readonly tenantId: TenantId;
   readonly limit: number;

package/src/flow-pins.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AgentId } from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import { type Flow, type FlowPins, flowPinsDigest, flowRefs } from '@kindgi/flow';
+import { latestVersion } from '@kindgi/tools';
+import type { Cursor, FlowId, ProjectId, TenantId, ToolId } from '@kindgi/types';
+
+import type { AgentRegistryBinding } from './agent-binding.js';
+import { type UnpinnableRef, activeToolVersions } from './agent-pins.js';
+import { type DeployedVersionOutcome, deployVersion } from './deploy-versions.js';
+import type { FlowRegistryBinding } from './flow-binding.js';
+import type { ToolRegistryBinding } from './tool-binding.js';
+
+export type FlowPinsOutcome =
+  | { readonly kind: 'ok'; readonly pins: FlowPins }
+  | { readonly kind: 'unpinnable'; readonly issues: readonly UnpinnableRef[] };
+
+/**
+ * Pin a flow version when it's published: each tool it runs, and each
+ * agent it runs at no named version, to its latest active version now
+ * (what a run would have bound), so every run of the version uses those.
+ * A tool or agent with no published version makes the flow unpinnable:
+ * the caller refuses the publish, naming each, rather than store a
+ * partly pinned version.
+ */
+export async function resolveFlowPins(
+  tools: ToolRegistryBinding,
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  flow: Flow,
+): Promise<FlowPinsOutcome> {
+  const refs = flowRefs(flow);
+  const pinned: { tools: Record<string, string>; agents: Record<string, string> } = {
+    tools: {},
+    agents: {},
+  };
+  const issues: UnpinnableRef[] = [];
+  for (const id of refs.tools) {
+    const latest = latestVersion(await activeToolVersions(tools, tenantId, id as ToolId));
+    if (latest !== undefined) pinned.tools[id] = latest;
+    else
+      issues.push({
+        path: '/nodes',
+        message: `tool "${id}" has no published version; publish the tool first`,
+      });
+  }
+  for (const id of refs.agents) {
+    const latest = await agents.get({ tenantId, agentId: id as AgentId });
+    if (latest !== null) pinned.agents[id] = latest.version as unknown as string;
+    else
+      issues.push({
+        path: '/nodes',
+        message: `agent "${id}" has no published version; publish the agent first`,
+      });
+  }
+  if (issues.length > 0) return { kind: 'unpinnable', issues };
+  return { kind: 'ok', pins: pinned };
+}
+
+export interface PublishDeployedFlowInput {
+  readonly flows: FlowRegistryBinding;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  /** The flow as the pack defines it, with no pins. */
+  readonly flow: Flow;
+  readonly pins: FlowPins;
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+/** Register a deployed flow with its pins, by the deploy rule (`deployVersion`). */
+export async function publishDeployedFlow(
+  input: PublishDeployedFlowInput,
+): Promise<DeployedVersionOutcome> {
+  const { flows, tenantId, projectId, flow, pins, enqueueTuples } = input;
+  return deployVersion<Flow>({
+    label: `flow "${flow.id as unknown as string}"`,
+    definition: flow,
+    pins,
+    pinsDigest: flowPinsDigest(pins),
+    existing: await allFlowVersions(flows, tenantId, flow.id),
+    publish: async (version) => {
+      const outcome = await flows.publish({ tenantId, projectId, flow: version, enqueueTuples });
+      if (outcome.kind === 'ok') return 'ok';
+      return outcome.kind === 'project-not-found' ? 'skipped' : 'taken';
+    },
+  });
+}
+
+/** Page size for reading a flow's versions. */
+const VERSIONS_PAGE = 200;
+
+/** Every active version of a flow. */
+async function allFlowVersions(
+  flows: FlowRegistryBinding,
+  tenantId: TenantId,
+  flowId: FlowId,
+): Promise<readonly Flow[]> {
+  const versions: Flow[] = [];
+  let cursor: Cursor | undefined;
+  do {
+    const page = await flows.listVersions({
+      tenantId,
+      flowId,
+      limit: VERSIONS_PAGE,
+      ...(cursor !== undefined && { cursor }),
+    });
+    versions.push(...page.data);
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return versions;
+}