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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.4-rc.0",
+  "version": "0.1.4-rc.2",
   "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,30 +32,30 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.4-rc.0",
-    "@kindgi/audit-events": "0.1.4-rc.0",
-    "@kindgi/compliance": "0.1.4-rc.0",
-    "@kindgi/authz": "0.1.4-rc.0",
-    "@kindgi/blob-binding": "0.1.4-rc.0",
-    "@kindgi/capabilities": "0.1.4-rc.0",
-    "@kindgi/crypto": "0.1.4-rc.0",
-    "@kindgi/flow": "0.1.4-rc.0",
-    "@kindgi/guardrails": "0.1.4-rc.0",
-    "@kindgi/memory": "0.1.4-rc.0",
-    "@kindgi/platform": "0.1.4-rc.0",
-    "@kindgi/provenance": "0.1.4-rc.0",
-    "@kindgi/runtime": "0.1.4-rc.0",
-    "@kindgi/policy-contract": "0.1.4-rc.0",
-    "@kindgi/schema": "0.1.4-rc.0",
-    "@kindgi/tools": "0.1.4-rc.0",
-    "@kindgi/types": "0.1.4-rc.0",
+    "@kindgi/agents": "0.1.4-rc.2",
+    "@kindgi/audit-events": "0.1.4-rc.2",
+    "@kindgi/compliance": "0.1.4-rc.2",
+    "@kindgi/authz": "0.1.4-rc.2",
+    "@kindgi/blob-binding": "0.1.4-rc.2",
+    "@kindgi/capabilities": "0.1.4-rc.2",
+    "@kindgi/crypto": "0.1.4-rc.2",
+    "@kindgi/flow": "0.1.4-rc.2",
+    "@kindgi/guardrails": "0.1.4-rc.2",
+    "@kindgi/memory": "0.1.4-rc.2",
+    "@kindgi/platform": "0.1.4-rc.2",
+    "@kindgi/provenance": "0.1.4-rc.2",
+    "@kindgi/runtime": "0.1.4-rc.2",
+    "@kindgi/policy-contract": "0.1.4-rc.2",
+    "@kindgi/schema": "0.1.4-rc.2",
+    "@kindgi/tools": "0.1.4-rc.2",
+    "@kindgi/types": "0.1.4-rc.2",
     "@scalar/hono-api-reference": "^0.12.2",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.4-rc.0",
-    "@kindgi/specs": "0.1.4-rc.0",
-    "@kindgi/testing": "0.1.4-rc.0",
+    "@kindgi/audit-events-inmemory": "0.1.4-rc.2",
+    "@kindgi/specs": "0.1.4-rc.2",
+    "@kindgi/testing": "0.1.4-rc.2",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",

package/src/agent-binding.ts

@@ -4,7 +4,9 @@
 import type { Agent, AgentId } from '@kindgi/agents';
 import type { TupleEnqueueHook } from '@kindgi/authz';
 import type { Scope } from '@kindgi/platform';
-import type { Cursor, ProjectId, Semver, TenantId } from '@kindgi/types';
+import type { Cursor, LiveScope, ProjectId, Semver, TenantId } from '@kindgi/types';
+
+import type { RegistryReadOnly } from './registry-read-only.js';
 
 /**
  * Caller-plugged surface for the agent catalog. Same shape as
@@ -22,6 +24,13 @@ import type { Cursor, ProjectId, Semver, TenantId } from '@kindgi/types';
  * cursor round-trips as a string; it never inspects the payload.
  */
 export interface AgentRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its agents): 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 agents (latest version per id, sorted by
    * agent id ascending). Optional `nameFilter` is a prefix match on the
@@ -71,7 +80,8 @@ export interface AgentRegistryBinding {
    * Soft-tombstone a specific `(agentId, version)`. Returns
    * `{ unregistered: true }` on success; `{ unregistered: false }`
    * when the version was unknown OR already tombstoned — the route
-   * flips the latter to `404`. Head row is preserved; when this
+   * flips the latter to `404` — or, with `live`, when it's a scope's live
+   * version (`409 agent-version-live`). Head row is preserved; when this
    * unregister leaves NO active versions, the agent has no latest
    * version — it enters the derived "retired" state
    * (GET returns 410 gone) but the identity persists. Publish of a
@@ -229,6 +239,15 @@ export type AgentPublishOutcome =
 
 export type AgentUnregisterOutcome = {
   readonly unregistered: boolean;
+  /**
+   * Set when the version wasn't unregistered because it's live: the
+   * scopes whose live pin it is (evals step 4). Unregister stops a version
+   * being chosen, and a live pin is a standing choice, so the operator
+   * moves those pins first (rollback, unpin, or promote another version).
+   * The route answers `409 agent-version-live`. Absent: a registry that
+   * doesn't know live versions, as before.
+   */
+  readonly live?: readonly LiveScope[];
 };
 
 export type AgentReinstateVersionOutcome =

package/src/agent-pins.ts

@@ -10,6 +10,7 @@ import type { AgentRegistryBinding } from './agent-binding.js';
 import type { BlockRegistryBinding } from './block-binding.js';
 import { resolveBlockPins } from './block-pins.js';
 import { type DeployedVersionOutcome, deployVersion } from './deploy-versions.js';
+import { PublishRefused } from './publish-refused.js';
 import type { ToolRegistryBinding } from './tool-binding.js';
 
 /** One block reference that matched no published version. */
@@ -120,7 +121,8 @@ export async function publishDeployedAgent(
     publish: async (version) => {
       const outcome = await agents.publish({ tenantId, projectId, agent: version, enqueueTuples });
       if (outcome.kind === 'ok') return 'ok';
-      return outcome.kind === 'project-not-found' ? 'skipped' : 'taken';
+      if (outcome.kind === 'already-registered') return 'taken';
+      throw new PublishRefused('agent', `${agent.id}@${version.version}`, outcome.kind);
     },
   });
 }

package/src/app.ts

@@ -48,6 +48,7 @@ import type {
 } from './identity-provider-binding.js';
 import type { ImageRegistryBinding } from './image-registry-binding.js';
 import type { JudgmentRegistryBinding } from './judgment-binding.js';
+import type { AgentReleaseBindings } from './live-version-binding.js';
 import type { MCPClientProbeBinding, MCPEndpointRegistryBinding } from './mcp-endpoint-binding.js';
 import type { MemoryBinding } from './memory-binding.js';
 import { type TokenResolver, bearerAuthMiddleware } from './middleware/auth.js';
@@ -59,6 +60,7 @@ import {
   idempotencyMiddleware,
 } from './middleware/idempotency.js';
 import { principalMiddleware } from './middleware/principal.js';
+import { PROJECT_REF_ROUTES, refuseBadProjectId } from './middleware/project-ref.js';
 import { publicRunCorsMiddleware, publicRunRouteMatcher } from './middleware/public-run-routes.js';
 import { requestIdMiddleware } from './middleware/request-id.js';
 import { sigv4Middleware } from './middleware/sigv4.js';
@@ -93,6 +95,7 @@ import { evalRunsRouters } from './routes/eval-runs.js';
 import { evalSuitesRouter } from './routes/eval-suites.js';
 import { eventTriggersRouter } from './routes/event-triggers.js';
 import { flowsRouter } from './routes/flows.js';
+import { gatePoliciesRouter } from './routes/gate-policies.js';
 import { guardrailsRouter } from './routes/guardrails.js';
 import { identityRouter } from './routes/identity.js';
 import { judgedSuitesRouter } from './routes/judged-suites.js';
@@ -609,6 +612,13 @@ export interface CreateAppInput {
    * and `GET /v1/eval-suites/:suiteId/versions/:version/cases`.
    */
   readonly evalCaseStore?: EvalCaseStoreBinding;
+  /**
+   * Optional. Live versions of agents per scope, and their promotions
+   * (`/v1/agents/{id}/live`, `/live-versions`, `/promotions`,
+   * `/live/rollback`, `/live/unpin`). Absent → a run takes the latest
+   * version, as before.
+   */
+  readonly agentReleases?: AgentReleaseBindings;
   /**
    * Optional. Push-based pub/sub binding used by SSE endpoints to
    * deliver run events without polling. When present, `GET
@@ -963,6 +973,11 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
 
   const tenantHierarchyBinding: TenantHierarchyBinding = input.tenantHierarchyBinding;
   v1.use('*', idempotencyMiddleware(input.idempotencyStore ?? createInMemoryIdempotencyStore()));
+  // A `projectId` in a write's body that the route can't use is refused
+  // before any binding sees it: a 400 if it isn't a UUID, a 404 if it
+  // names no project (T247).
+  const projectRef = refuseBadProjectId(input.projectBinding);
+  for (const path of PROJECT_REF_ROUTES) v1.use(path, projectRef);
   v1.route(
     '/runs',
     runsRouter(
@@ -1001,7 +1016,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
   // so `/v1/approvals/reviewers/*` resolves here rather than being
   // captured by the `:approvalId` param on the approvals router.
   if (input.reviewerRegistry !== undefined) {
-    v1.route('/approvals/reviewers', reviewersRouter(input.reviewerRegistry));
+    v1.route('/approvals/reviewers', reviewersRouter(input.reviewerRegistry, authorizer));
   }
   if (input.reviewerBinding !== undefined && input.hitlBinding !== undefined) {
     v1.route(
@@ -1029,9 +1044,22 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
   if (input.agentRegistry !== undefined) {
     v1.route(
       '/agents',
-      agentsRouter(input.agentRegistry, authorizer, input.toolRegistry, input.blockRegistry),
+      agentsRouter(
+        input.agentRegistry,
+        authorizer,
+        input.toolRegistry,
+        input.blockRegistry,
+        input.agentReleases,
+        {
+          ...(input.evalRunBinding !== undefined && { evalRuns: input.evalRunBinding }),
+          ...(input.projectBinding !== undefined && { projects: input.projectBinding }),
+        },
+      ),
     );
   }
+  if (input.agentReleases?.gatePolicies !== undefined) {
+    v1.route('/gate-policies', gatePoliciesRouter(input.agentReleases.gatePolicies, authorizer));
+  }
   if (input.flowRegistry !== undefined) {
     v1.route(
       '/flows',
@@ -1039,7 +1067,11 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
         input.flowRegistry,
         authorizer,
         input.toolRegistry !== undefined && input.agentRegistry !== undefined
-          ? { tools: input.toolRegistry, agents: input.agentRegistry }
+          ? {
+              tools: input.toolRegistry,
+              agents: input.agentRegistry,
+              ...(input.agentReleases !== undefined && { live: input.agentReleases.live }),
+            }
           : undefined,
       ),
     );
@@ -1149,6 +1181,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
         authorizer,
         input.conversationBinding,
         input.flowRegistry,
+        input.reviewerBinding,
       ),
     );
     v1.route('/judge-classes', judgeClassesRouter(input.judgmentRegistry, authorizer));
@@ -1265,6 +1298,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
         }),
         ...(input.agentRegistry !== undefined && { agentRegistry: input.agentRegistry }),
         ...(input.flowRegistry !== undefined && { flowRegistry: input.flowRegistry }),
+        ...(input.agentReleases !== undefined && { liveVersions: input.agentReleases.live }),
         // The deployments router's agents publish loop resolves the
         // Default project through this binding. Optional at wiring so
         // app compositions without a project binding still boot; the loop
@@ -1289,7 +1323,16 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
     // `evalSuiteRegistry` binding: the dispatcher itself surfaces
     // `suite-not-found` when the caller-plugged binding can't resolve
     // the suite id, so the API layer stays consumer-neutral.
-    const evalRuns = evalRunsRouters(input.evalRunBinding);
+    const evalRuns = evalRunsRouters(
+      input.evalRunBinding,
+      input.flowRegistry !== undefined
+        ? {
+            flows: input.flowRegistry,
+            ...(input.agentRegistry !== undefined && { agents: input.agentRegistry }),
+            ...(input.toolRegistry !== undefined && { tools: input.toolRegistry }),
+          }
+        : undefined,
+    );
     v1.route('/eval-suites', evalRuns.start);
     v1.route('/eval-runs', evalRuns.readback);
   }

package/src/deploy-versions.ts

@@ -21,8 +21,7 @@ export interface PinnedDefinition {
  *
  * - `registered`: the definition's version was free, and is now
  *   registered with these pins;
- * - `unchanged`: it's registered with the same definition and pins (or
- *   its project is gone, which a deploy has always left as it is);
+ * - `unchanged`: it's registered with the same definition and pins;
  * - `reused`: an earlier deploy already registered this definition and
  *   these pins under another number (`version`), so a redeploy changes
  *   nothing;
@@ -39,8 +38,8 @@ export type DeployedVersionOutcome =
       readonly pinChanges?: readonly PinChange[];
     };
 
-/** What registering one version did: stored it, found the number taken, or left it (no project). */
-export type PublishOutcome = 'ok' | 'taken' | 'skipped';
+/** What registering one version did: stored it, or found the number taken. */
+export type PublishOutcome = 'ok' | 'taken';
 
 export interface DeployVersionInput<T extends PinnedDefinition> {
   /** Names the definition in an error, e.g. `agent "acme.matcher"`. */
@@ -51,7 +50,11 @@ export interface DeployVersionInput<T extends PinnedDefinition> {
   readonly pinsDigest: string;
   /** Every active version registered under the definition's id. */
   readonly existing: readonly T[];
-  /** Register one version. */
+  /**
+   * Register one version: `taken` when the number is (an unregistered
+   * version holds it). A registry's refusal (e.g. `project-not-found`)
+   * throws `PublishRefused`, and the deploy rolls back.
+   */
   readonly publish: (version: T) => Promise<PublishOutcome>;
 }
 
@@ -78,9 +81,7 @@ export async function deployVersion<T extends PinnedDefinition>(
   if (atAuthored !== undefined && same(atAuthored)) return { kind: 'unchanged', version: authored };
   if (atAuthored === undefined) {
     const outcome = await input.publish({ ...definition, pins, pinsDigest });
-    if (outcome !== 'taken') {
-      return { kind: outcome === 'ok' ? 'registered' : 'unchanged', version: authored };
-    }
+    if (outcome === 'ok') return { kind: 'registered', version: authored };
     // Taken with no active version: an unregistered version holds the
     // number. Register the next one.
   }
@@ -103,9 +104,7 @@ export async function deployVersion<T extends PinnedDefinition>(
   }
   const taken = new Set(existing.map((v) => v.version));
   const version = await registerNextFree(input, reason, taken);
-  return version === undefined
-    ? { kind: 'unchanged', version: authored }
-    : { kind: 'renumbered', version, reason, ...changes };
+  return { kind: 'renumbered', version, reason, ...changes };
 }
 
 /** Why the definition's version can't be registered as it is. */
@@ -120,13 +119,12 @@ function derivationReason(
 /**
  * Register the definition with its pins under the first free version
  * after its own (`nextVersion`), recording where it came from.
- * `undefined` when it was left as it is (its project is gone).
  */
 async function registerNextFree<T extends PinnedDefinition>(
   input: DeployVersionInput<T>,
   reason: VersionDerivationReason,
   taken: ReadonlySet<string>,
-): Promise<string | undefined> {
+): Promise<string> {
   const { definition, pins, pinsDigest } = input;
   const authored = definition.version;
   let candidate = nextVersion(authored);
@@ -140,7 +138,6 @@ async function registerNextFree<T extends PinnedDefinition>(
         derivedFrom: { version: authored, reason },
       });
       if (outcome === 'ok') return candidate;
-      if (outcome === 'skipped') return undefined;
       // Taken: an unregistered version holds this one too.
     }
     candidate = nextVersion(candidate);
@@ -151,7 +148,7 @@ async function registerNextFree<T extends PinnedDefinition>(
 }
 
 /** A definition: everything but its version and what the runtime sets. */
-function definitionKey(definition: PinnedDefinition): string {
+export function definitionKey(definition: PinnedDefinition): string {
   const { version: _v, pins: _p, pinsDigest: _d, derivedFrom: _f, ...rest } = definition;
   return canonicalize(rest);
 }

package/src/derive-agent-version.ts

@@ -16,6 +16,7 @@ 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';
+import { definitionKey } from './deploy-versions.js';
 
 /** Which data-block pins to swap, by kind then block id → exact version. */
 export interface PinSwaps {
@@ -48,6 +49,8 @@ export interface SwapIssue {
 
 export type DeriveAgentVersionOutcome =
   | { readonly kind: 'ok'; readonly agent: Agent }
+  /** An active version already has this definition and these pins: that one, unchanged. */
+  | { readonly kind: 'reused'; readonly agent: Agent }
   | { readonly kind: 'not-found' }
   | { readonly kind: 'unpinned' }
   | { readonly kind: 'invalid'; readonly issues: readonly SwapIssue[] }
@@ -63,7 +66,10 @@ const MAX_TRIES = 100;
  * 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).
+ * agent's highest version (versions never change). If an active version
+ * already holds that definition and those pins (the same swap derived
+ * before, or a deploy that registered it), that version is returned
+ * unchanged (`reused`) rather than a duplicate.
  *
  * Only data-block pins swap: a swap must name a block the version
  * already references (adding one is a code change), at a published,
@@ -114,6 +120,11 @@ async function publishNextFree(
 ): Promise<DeriveAgentVersionOutcome> {
   const { agents, tenantId, agentId } = input;
   const active = await activeAgentVersions(agents, tenantId, agentId);
+  // The same swap again (or a deploy that registered it) finds the
+  // version that already holds it: versions are never duplicated.
+  const key = definitionKey(derived);
+  const same = active.find((a) => a.pinsDigest === derived.pinsDigest && definitionKey(a) === key);
+  if (same !== undefined) return { kind: 'reused', agent: same };
   const highest =
     latestVersion(active.map((a) => a.version as unknown as string)) ??
     (derived.version as unknown as string);

package/src/errors.ts

@@ -67,6 +67,7 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'duplicate-edge-id': 409,
   'agent-version-mismatch': 409,
   'agent-already-registered': 409,
+  'registry-read-only': 409,
   'agent-gone': 410,
   'flow-gone': 410,
   'policy-gone': 410,
@@ -160,6 +161,8 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   // Admin plane — policies.
   'policy-not-found': 404,
   'policy-already-registered': 409,
+  'policy-scope-taken': 409,
+  'policy-scope-changed': 409,
   // Admin plane — eval suites.
   'block-not-found': 404,
   'block-already-registered': 409,
@@ -173,10 +176,33 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'judge-class-not-found': 404,
   'judge-class-name-taken': 409,
   'judge-class-not-applicable': 400,
+  // The judge class is restricted (`assertableBy`), and the caller isn't one who may assert it.
+  'judge-class-not-allowed': 403,
+  // Live versions of agents and their promotions.
+  'agent-version-not-found': 404,
+  'promotion-not-found': 404,
+  'nothing-to-roll-back': 409,
+  'not-pinned': 409,
+  // The gate (evals step 4b).
+  'gate-failed': 422,
+  'promotion-superseded': 409,
+  // The binding can't record a gated promotion, so one a policy applies to is refused.
+  'promotion-gate-unsupported': 501,
+  'separate-approver-required': 403,
+  'gate-policy-not-found': 404,
+  'gate-policy-already-registered': 409,
+  'gate-policy-scope-taken': 409,
+  'gate-policy-scope-changed': 409,
+  'gate-policy-scope-unpinned': 409,
+  'gate-policy-needs-pin': 409,
+  /** Unregister: the version is live in a scope; move that pin first. */
+  'agent-version-live': 409,
   '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,
+  // Authorization is enforced, but a membership change can't be kept in step with it.
+  'authz-membership-unsupported': 501,
   'eval-run-already-terminal': 409,
   'dispatcher-not-registered': 422,
   'dispatcher-input-invalid': 400,

package/src/eval-case-binding.ts

@@ -31,6 +31,13 @@ export interface JudgedItemSummary extends JudgedItem {
   readonly yesWeight: number;
   /** The weight behind all judgments of the item. */
   readonly totalWeight: number;
+  /**
+   * The same two, counting only judgments recorded while their class was
+   * restricted (`Judgment.restricted`), for a comparison weighted
+   * `restricted-only`. Absent from a test set built before restrictions:
+   * no restricted evidence.
+   */
+  readonly restricted?: { readonly yesWeight: number; readonly totalWeight: number };
   /** The reasons given, newest first. */
   readonly reasons: readonly { readonly verdict: 'yes' | 'no'; readonly reason: string }[];
 }

package/src/eval-run-binding.ts

@@ -2,8 +2,18 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { Scope } from '@kindgi/platform';
-import type { Cursor, FlowId, ProjectId, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
+import type {
+  Cursor,
+  FlowId,
+  ProjectId,
+  RunId,
+  ScopeSegment,
+  Semver,
+  TenantId,
+  Timestamp,
+} from '@kindgi/types';
 
 import type { EvalKind } from './eval-suite-binding.js';
 
@@ -122,7 +132,8 @@ export interface EvalRunFilter {
  * 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).
+ *   - `{ live }`: the version live in a scope: a project, and a segment
+ *     path in it (coarse to fine, as live versions resolve it).
  */
 export type EvalBaseline =
   | 'recorded'
@@ -130,13 +141,22 @@ export type EvalBaseline =
   | {
       readonly live: {
         readonly projectId?: ProjectId;
-        readonly segments?: Readonly<Record<string, string>>;
+        /** A segment path in `projectId`, coarse to fine. */
+        readonly segments?: readonly ScopeSegment[];
       };
     };
 
 /** Whether replayed reads use the past run's results when it has them, or run live. */
 export type EvalReads = 'recorded' | 'live';
 
+/**
+ * Which judgments a comparison counts: every judgment at its class's
+ * weight (`as-recorded`, the default), or only those recorded while their
+ * class was restricted (`assertableBy`), the others weighing 0
+ * (`restricted-only`; T200).
+ */
+export type EvalClassWeights = 'as-recorded' | 'restricted-only';
+
 /** How a comparison eval run runs its cases (absent: the run isn't a comparison). */
 export interface EvalComparison {
   readonly baseline: EvalBaseline;
@@ -145,6 +165,14 @@ export interface EvalComparison {
   readonly repetitions: number;
   /** How many ranked items `weightedPrecisionAtK` looks at (1–100). */
   readonly k: number;
+  /**
+   * For a flow candidate: agents and tools its replays run at other exact
+   * versions than the flow version's pins ("this flow, with `acme.scorer`
+   * at 0.4.0"), without publishing a new flow version.
+   */
+  readonly versions?: FlowVersionOverrides;
+  /** Which judgments count (absent: `as-recorded`). */
+  readonly classWeights?: EvalClassWeights;
 }
 
 export interface EvalRunStartInput {

package/src/eval-run-dispatcher.ts

@@ -4,6 +4,7 @@
 import { randomUUID } from 'node:crypto';
 
 import type { ReplayTurnReport } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { RunReplayRef } from '@kindgi/runtime';
 import type { ProjectId, RunId, TenantId, Timestamp } from '@kindgi/types';
 
@@ -63,6 +64,8 @@ export interface EvalRunSubjectInvokeInput {
   readonly replay?: RunReplayRef;
   /** The conversation before the past turn, oldest first: a replayed turn starts from it. */
   readonly history?: readonly unknown[];
+  /** A flow target's agents and tools at other exact versions (`EvalComparison.versions`). */
+  readonly versions?: FlowVersionOverrides;
 }
 
 export interface EvalRunSubjectInvokeOutcome {

package/src/flow-binding.ts

@@ -6,6 +6,8 @@ import type { Flow } from '@kindgi/flow';
 import type { Scope } from '@kindgi/platform';
 import type { Cursor, FlowId, ProjectId, TenantId } from '@kindgi/types';
 
+import type { RegistryReadOnly } from './registry-read-only.js';
+
 /**
  * Caller-plugged surface for the flow catalog. Mirrors
  * `AgentRegistryBinding` 1:1 — the API package does NOT own registry
@@ -26,6 +28,13 @@ import type { Cursor, FlowId, ProjectId, TenantId } from '@kindgi/types';
  * cursor round-trips as a string; it never inspects the payload.
  */
 export interface FlowRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its flows): 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 flows (latest version per id, sorted by
    * flow id ascending). Optional `nameFilter` is a prefix match on the

package/src/flow-pins.ts

@@ -11,6 +11,8 @@ 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 { LiveVersionBinding } from './live-version-binding.js';
+import { PublishRefused } from './publish-refused.js';
 import type { ToolRegistryBinding } from './tool-binding.js';
 
 export type FlowPinsOutcome =
@@ -18,18 +20,32 @@ export type FlowPinsOutcome =
   | { 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.
+ * Where a flow version is published, so its agent pins are what a run
+ * there would get: the agents' live versions for the project.
+ */
+export interface FlowPinsLive {
+  readonly binding: LiveVersionBinding;
+  readonly projectId: ProjectId;
+}
+
+/**
+ * Pin a flow version when it's published, to what a run would have bound
+ * then, so every run of the version uses those: each tool it runs to its
+ * latest active version, and each agent it runs at no named version to
+ * the version a run that names none gets in the flow's project. That's
+ * the agent's live version there (project, then its org, then the
+ * tenant), with `live`, else its latest. A gated agent's flow runs what
+ * its promotions let go live, not an unpromoted newer version. 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,
+  live?: FlowPinsLive,
 ): Promise<FlowPinsOutcome> {
   const refs = flowRefs(flow);
   const pinned: { tools: Record<string, string>; agents: Record<string, string> } = {
@@ -47,8 +63,8 @@ export async function resolveFlowPins(
       });
   }
   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;
+    const version = await implicitAgentVersion(agents, live, tenantId, id);
+    if (version !== undefined) pinned.agents[id] = version;
     else
       issues.push({
         path: '/nodes',
@@ -59,6 +75,29 @@ export async function resolveFlowPins(
   return { kind: 'ok', pins: pinned };
 }
 
+/**
+ * The version a run of agent `id` that names none gets now: its live
+ * version for `live`'s project when one is pinned on the way up, else its
+ * latest; `undefined` when it has no published version.
+ */
+async function implicitAgentVersion(
+  agents: AgentRegistryBinding,
+  live: FlowPinsLive | undefined,
+  tenantId: TenantId,
+  id: string,
+): Promise<string | undefined> {
+  if (live !== undefined) {
+    const resolved = await live.binding.resolve({
+      tenantId,
+      agentId: id,
+      projectId: live.projectId,
+    });
+    if (resolved !== null) return resolved.version as unknown as string;
+  }
+  const latest = await agents.get({ tenantId, agentId: id as AgentId });
+  return latest === null ? undefined : (latest.version as unknown as string);
+}
+
 export interface PublishDeployedFlowInput {
   readonly flows: FlowRegistryBinding;
   readonly tenantId: TenantId;
@@ -83,7 +122,8 @@ export async function publishDeployedFlow(
     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';
+      if (outcome.kind === 'already-registered') return 'taken';
+      throw new PublishRefused('flow', `${flow.id}@${version.version}`, outcome.kind);
     },
   });
 }