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

package/src/openapi/schemas.ts

@@ -194,6 +194,7 @@ export const RunSchema: JsonSchema = {
       type: 'string',
       description: 'Set on a replay run: the eval run that started it.',
     },
+    versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
     publicAccessToken: {
       type: 'string',
       description:
@@ -1287,6 +1288,21 @@ export const FlowPinsSchema: JsonSchema = {
   },
 };
 
+export const FlowVersionOverridesSchema: JsonSchema = {
+  description:
+    "Agents and tools a flow runs 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: a comparison's flow candidate (`versions` on the start body and the run's `comparison`), and the flow runs that replay it (a run's `versions`). Each id must be an agent or tool the flow uses.",
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    tools: { ...PinMapSchema, description: 'Tool id → exact version.' },
+    agents: {
+      ...PinMapSchema,
+      description:
+        'Agent id → exact version, for agent nodes with or without a version of their own.',
+    },
+  },
+};
+
 export const PublishFlowBodySchema: JsonSchema = {
   description:
     'Full flow definition. Validated server-side via `@kindgi/flow.loadFlow` — validation failures return `400 validation-failed` with the issue list under `details.issues`.',
@@ -4766,6 +4782,342 @@ export const EvalComparisonSchema: JsonSchema = {
     },
     repetitions: { type: 'integer', minimum: 1, maximum: 10 },
     k: { type: 'integer', minimum: 1, maximum: 100 },
+    versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
+  },
+};
+
+// ---------------- comparison results (a `judged` eval run's `result`) ----------------
+
+const nullableNumber = { type: ['number', 'null'] } as const;
+
+export const ComparisonMetricSchema: JsonSchema = {
+  description:
+    "One metric, the recorded runs beside the candidate. `null` where a side had no judged evidence; `n` / `weight` are the candidate's evidence (cases with judged items, and the judgment weight behind them), `baselineN` / `baselineWeight` the recorded side's.",
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'baseline',
+    'candidate',
+    'delta',
+    'n',
+    'weight',
+    'baselineN',
+    'baselineWeight',
+    'direction',
+  ],
+  properties: {
+    baseline: nullableNumber,
+    candidate: nullableNumber,
+    delta: nullableNumber,
+    n: { type: 'integer', minimum: 0 },
+    weight: { type: 'number', minimum: 0 },
+    baselineN: { type: 'integer', minimum: 0 },
+    baselineWeight: { type: 'number', minimum: 0 },
+    direction: { type: 'string', enum: ['higher'] },
+    k: {
+      type: 'integer',
+      minimum: 1,
+      description: '`weightedPrecisionAtK`: the ranked items it looked at.',
+    },
+    spread: {
+      type: 'number',
+      description: "With more than one repetition: the candidate's max − min across them.",
+    },
+  },
+};
+
+export const ComparisonCandidateSchema: JsonSchema = {
+  description:
+    'What ran on the cases: an agent version, or a flow version (with any versions it swapped in).',
+  oneOf: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'agentId', 'version'],
+      properties: {
+        kind: { type: 'string', enum: ['agent'] },
+        agentId: { type: 'string' },
+        version: { type: 'string' },
+      },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'flowId', 'version'],
+      properties: {
+        kind: { type: 'string', enum: ['flow'] },
+        flowId: { type: 'string' },
+        version: { type: 'string' },
+        versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
+      },
+    },
+  ],
+};
+
+export const JudgedComparisonSummarySchema: JsonSchema = {
+  description:
+    'What a comparison concluded: the candidate beside the recorded runs, the case counts, and the metrics. What a promotion gate reads.',
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'evalRunId',
+    'status',
+    'completedAt',
+    'suite',
+    'candidate',
+    'baseline',
+    'scope',
+    'cases',
+    'diverged',
+    'refusedWrites',
+    'errors',
+    'stopped',
+    'reads',
+    'sampling',
+    'repetitions',
+    'metrics',
+  ],
+  properties: {
+    evalRunId: { type: 'string' },
+    status: { type: 'string', enum: ['completed', 'partial', 'failed'] },
+    completedAt: { type: 'string', format: 'date-time' },
+    suite: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id', 'version'],
+      properties: { id: { type: 'string' }, version: { type: 'string' } },
+    },
+    candidate: { $ref: '#/components/schemas/ComparisonCandidate' },
+    baseline: {
+      description:
+        "What the candidate was compared with: `recorded` (the test set's recorded runs, with the versions that served them), or another version.",
+      oneOf: [
+        {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind', 'versions'],
+          properties: {
+            kind: { type: 'string', enum: ['recorded'] },
+            versions: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['version', 'cases'],
+                properties: {
+                  agentId: { type: 'string' },
+                  flowId: { type: 'string' },
+                  version: { type: 'string' },
+                  cases: { type: 'integer', minimum: 0 },
+                },
+              },
+            },
+          },
+        },
+        {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind', 'agentId', 'version', 'via'],
+          properties: {
+            kind: { type: 'string', enum: ['version'] },
+            agentId: { type: 'string' },
+            version: { type: 'string' },
+            via: { type: 'string', enum: ['explicit', 'live'] },
+            liveScope: { type: 'object', additionalProperties: true },
+          },
+        },
+      ],
+    },
+    scope: {
+      type: 'object',
+      additionalProperties: false,
+      description: "Where the test set's judgments came from.",
+      properties: { projectId: { type: 'string' } },
+    },
+    cases: { type: 'integer', minimum: 0 },
+    diverged: {
+      type: 'integer',
+      minimum: 0,
+      description: "Cases where a read with no recording ran live under `reads: 'recorded'`.",
+    },
+    refusedWrites: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Tool calls refused across the cases (what the candidate would have done).',
+    },
+    errors: { type: 'integer', minimum: 0, description: 'Cases none of whose repetitions ran.' },
+    stopped: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        "Flow cases that stopped at a write the replay refused: no output to score, so they're left out of the metrics.",
+    },
+    reads: { type: 'string', enum: ['recorded', 'live'] },
+    sampling: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['models'],
+      properties: {
+        models: {
+          type: 'array',
+          description:
+            "The models that answered the candidate's replays, and how many replays each.",
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['providerId', 'model', 'runs'],
+            properties: {
+              providerId: { type: 'string' },
+              model: { type: 'string' },
+              runs: { type: 'integer', minimum: 0 },
+            },
+          },
+        },
+      },
+    },
+    repetitions: { type: 'integer', minimum: 1 },
+    metrics: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['weightedYesShare', 'judgedCoverage', 'weightedPrecisionAtK'],
+      properties: {
+        weightedYesShare: { $ref: '#/components/schemas/ComparisonMetric' },
+        judgedCoverage: { $ref: '#/components/schemas/ComparisonMetric' },
+        weightedPrecisionAtK: { $ref: '#/components/schemas/ComparisonMetric' },
+      },
+    },
+  },
+};
+
+const outputScore = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['yesWeight', 'totalWeight', 'items', 'judgedItems', 'topK'],
+  description:
+    "An output's score: Σ yesWeight and Σ totalWeight over its judged items, and over those among the first `k` ranked items.",
+  properties: {
+    yesWeight: { type: 'number' },
+    totalWeight: { type: 'number' },
+    items: { type: 'integer', minimum: 0 },
+    judgedItems: { type: 'integer', minimum: 0 },
+    topK: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['yesWeight', 'totalWeight'],
+      properties: { yesWeight: { type: 'number' }, totalWeight: { type: 'number' } },
+    },
+  },
+} as const;
+
+export const ComparisonCaseResultSchema: JsonSchema = {
+  description:
+    "One case of a comparison: its replay runs, the scores, the items kept, dropped and new, the tool calls, and why it didn't run when it didn't.",
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'caseId',
+    'runIds',
+    'baseline',
+    'candidate',
+    'diverged',
+    'refusedWrites',
+    'noContext',
+    'approvalSkipped',
+  ],
+  properties: {
+    caseId: { type: 'string' },
+    runIds: {
+      type: 'array',
+      items: { type: 'string' },
+      description: "The candidate's replay runs, one per repetition.",
+    },
+    baseline: outputScore,
+    candidate: { type: 'array', items: outputScore, description: 'One per repetition that ran.' },
+    changes: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kept', 'dropped', 'new'],
+      description: "The first repetition's items against the judged ones.",
+      properties: {
+        kept: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['key'],
+            properties: {
+              key: { type: 'string' },
+              rankBefore: { type: 'integer' },
+              rank: { type: 'integer' },
+            },
+          },
+        },
+        dropped: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['key'],
+            properties: { key: { type: 'string' }, rankBefore: { type: 'integer' } },
+          },
+        },
+        new: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['key', 'pointer'],
+            properties: {
+              key: { type: 'string' },
+              pointer: { type: 'string' },
+              rank: { type: 'integer' },
+            },
+          },
+        },
+      },
+    },
+    tools: {
+      type: 'array',
+      description: "The first repetition's tool calls, and what happened to each.",
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['step', 'callId', 'toolId', 'toolVersion', 'arguments', 'source'],
+        properties: {
+          step: { type: 'integer', minimum: 0 },
+          callId: { type: 'string' },
+          toolId: { type: 'string' },
+          toolVersion: { type: 'string' },
+          arguments: {},
+          source: { type: 'string', enum: ['live', 'recorded', 'refused'] },
+          reason: { type: 'string' },
+        },
+      },
+    },
+    diverged: { type: 'boolean' },
+    refusedWrites: { type: 'integer', minimum: 0 },
+    noContext: { type: 'boolean' },
+    approvalSkipped: { type: 'boolean' },
+    error: { type: 'string' },
+    stopped: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['toolId', 'arguments'],
+      description: 'Set when the replay stopped at a refused write: what it would have done.',
+      properties: { toolId: { type: 'string' }, arguments: {}, reason: { type: 'string' } },
+    },
+  },
+};
+
+export const JudgedComparisonResultSchema: JsonSchema = {
+  description:
+    "A comparison's `result` (a `judged` eval run's): the summary and each case. `EvalRun.result` stays an open object, since each kind has its own; the clients read it as this (TS `comparisonOf(run)`, Python `comparison_of(run)`).",
+  type: 'object',
+  additionalProperties: false,
+  required: ['summary', 'perCase'],
+  properties: {
+    summary: { $ref: '#/components/schemas/JudgedComparisonSummary' },
+    perCase: { type: 'array', items: { $ref: '#/components/schemas/ComparisonCaseResult' } },
   },
 };
 
@@ -4798,7 +5150,7 @@ export const EvalRunSchema: JsonSchema = {
       type: 'object',
       additionalProperties: true,
       description:
-        'Kind-specific opaque JSON. For `accuracy`, contains `{ passCount, totalCount, meanScore, perCase[] }`. For `judged` (a comparison), `{ summary, perCase[] }`: the summary has the baseline (the versions behind the recorded runs) and the candidate (`{ kind: "agent", agentId, version }` or `{ kind: "flow", flowId, version }`), the case counts (`cases`, `diverged`, `refusedWrites`, `errors`, and `stopped`: flow cases that stopped at a write the replay refused, left out of the metrics), the models that answered, and `metrics` (`weightedYesShare`, `judgedCoverage`, `weightedPrecisionAtK`, each `{ baseline, candidate, delta, n, weight, baselineN, baselineWeight, direction, k?, spread? }`); each case has its replay runs, the scores, the items kept, dropped and new, the tool calls with what happened to each, and `stopped` (what it would have done) when it stopped. Other kinds define their own shapes as their dispatchers ship.',
+        'Kind-specific opaque JSON. For `accuracy`, contains `{ passCount, totalCount, meanScore, perCase[] }`. For `judged` (a comparison), `{ summary, perCase[] }`: the summary has the baseline (the versions behind the recorded runs) and the candidate (`{ kind: "agent", agentId, version }` or `{ kind: "flow", flowId, version, versions? }`), the case counts (`cases`, `diverged`, `refusedWrites`, `errors`, and `stopped`: flow cases that stopped at a write the replay refused, left out of the metrics), the models that answered, and `metrics` (`weightedYesShare`, `judgedCoverage`, `weightedPrecisionAtK`, each `{ baseline, candidate, delta, n, weight, baselineN, baselineWeight, direction, k?, spread? }`); each case has its replay runs, the scores, the items kept, dropped and new, the tool calls with what happened to each, and `stopped` (what it would have done) when it stopped. Other kinds define their own shapes as their dispatchers ship.',
     },
     error: { type: 'string' },
     correlationId: { type: 'string' },
@@ -4831,9 +5183,10 @@ export const StartEvalRunBodySchema: JsonSchema = {
     reads: { type: 'string', enum: ['recorded', 'live'] },
     repetitions: { type: 'integer', minimum: 1, maximum: 10 },
     k: { type: 'integer', minimum: 1, maximum: 100 },
+    versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
   },
   description:
-    "Exactly one of `agentRef` or `flowRef` MUST be supplied. `dryRun: true` returns a plan preview without invoking the subject. For a `judged` suite (a test set), the run is a comparison: `agentRef` or `flowRef` with its `version` is the candidate, replayed on each case without doing anything the past run didn't (a flow stops at a write the replay refuses); `baseline` (default `'recorded'`), `reads` (default `recorded`), `repetitions` (default 1) and `k` (default 10) set how.",
+    "Exactly one of `agentRef` or `flowRef` MUST be supplied. `dryRun: true` returns a plan preview without invoking the subject. For a `judged` suite (a test set), the run is a comparison: `agentRef` or `flowRef` with its `version` is the candidate, replayed on each case without doing anything the past run didn't (a flow stops at a write the replay refuses); `baseline` (default `'recorded'`), `reads` (default `recorded`), `repetitions` (default 1) and `k` (default 10) set how. With `flowRef`, `versions` runs the flow with some of its agents or tools at other versions; an id the flow doesn't use, or a version that isn't published, is refused (`400 validation-failed`, each under `details.issues`).",
 };
 
 export const StartEvalRunResultSchema: JsonSchema = {
@@ -7189,6 +7542,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['DeriveAgentVersionBody', DeriveAgentVersionBodySchema],
   ['AgentPinSwaps', AgentPinSwapsSchema],
   ['FlowPins', FlowPinsSchema],
+  ['FlowVersionOverrides', FlowVersionOverridesSchema],
   ['PublishAgentBody', PublishAgentBodySchema],
   ['PublishAgentResult', PublishAgentResultSchema],
   ['UnregisterAgentResult', UnregisterAgentResultSchema],
@@ -7352,6 +7706,11 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['EvalRunFlowRef', EvalRunFlowRefSchema],
   ['EvalBaseline', EvalBaselineSchema],
   ['EvalComparison', EvalComparisonSchema],
+  ['ComparisonMetric', ComparisonMetricSchema],
+  ['ComparisonCandidate', ComparisonCandidateSchema],
+  ['JudgedComparisonSummary', JudgedComparisonSummarySchema],
+  ['ComparisonCaseResult', ComparisonCaseResultSchema],
+  ['JudgedComparisonResult', JudgedComparisonResultSchema],
   ['EvalRun', EvalRunSchema],
   ['EvalRunCollectionPage', EvalRunCollectionPageSchema],
   ['StartEvalRunBody', StartEvalRunBodySchema],

package/src/registry-read-only.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context, MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from './errors.js';
+import type { AppEnv } from './types.js';
+
+/**
+ * A registry that takes no writes: it serves its definitions from
+ * somewhere else (under `kindgi dev`, the pack's files). A binding that
+ * sets it has every write refused before the binding is called:
+ * publish, unregister and reinstate (and, for agents, deriving a
+ * version), and a deploy that would publish into it. The refusal is
+ * `409 registry-read-only` with `reason` as its message.
+ */
+export interface RegistryReadOnly {
+  /** Why, and what to do instead, in plain words: the refusal's message. */
+  readonly reason: string;
+}
+
+/** The refusal of a write to a read-only registry. */
+export function refuseReadOnly(c: Context<AppEnv>, readOnly: RegistryReadOnly) {
+  c.status(statusFor('registry-read-only') as never);
+  return c.json(
+    toWireError({ code: 'registry-read-only', message: readOnly.reason }, c.get('requestId')),
+  );
+}
+
+/**
+ * A router's writes (every method but GET and HEAD) are refused while
+ * its registry is read-only. Read at request time, so a binding can
+ * become writable without a restart.
+ */
+export function refuseWritesWhenReadOnly(
+  readOnly: () => RegistryReadOnly | undefined,
+): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const marker = readOnly();
+    if (marker === undefined || c.req.method === 'GET' || c.req.method === 'HEAD') return next();
+    return refuseReadOnly(c, marker);
+  };
+}

package/src/routes/agents.ts

@@ -24,6 +24,7 @@ import {
 } from '../derive-agent-version.js';
 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';
@@ -53,6 +54,12 @@ export function agentsRouter(
   blockRegistry?: BlockRegistryBinding,
 ): 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 — check the resource directly (ref('agent', businessId));
   // permissions cascade from the parent project because the
@@ -323,7 +330,7 @@ export function agentsRouter(
           toWireError(
             {
               code: 'validation-failed',
-              message: `Agent "${defined.value.id as unknown as string}" uses tool versions that aren't published (${resolved.issues.length} issue${resolved.issues.length === 1 ? '' : 's'})`,
+              message: `Agent "${defined.value.id as unknown as string}" uses tool or data-block versions it can't pin (${resolved.issues.length} issue${resolved.issues.length === 1 ? '' : 's'})`,
               issues: resolved.issues as unknown as Record<string, unknown>[],
             },
             requestId,
@@ -592,6 +599,8 @@ function derived(
     case 'ok':
       c.status(201);
       return c.json(serializeAgent(outcome.agent));
+    case 'reused':
+      return c.json(serializeAgent(outcome.agent));
     case 'not-found':
       return fail('agent-not-found', {
         code: 'agent-not-found',

package/src/routes/blocks.ts

@@ -184,14 +184,20 @@ export function blocksRouter(binding: BlockRegistryBinding, authorizer?: Authori
       return validationFailed(c, validated.error.message, validated.error.issues);
     const block = validated.value;
 
-    // A block keeps its kind, and a settings block's latest schema holds.
+    // A block keeps its kind. A settings version without a schema keeps
+    // the latest version's (stored on it, so the check carries forward to
+    // every later version); one that gives a schema replaces it.
     const latest = await binding.get({ tenantId, blockId: block.id });
     const continuity = continuityIssues(latest, block);
     if (continuity.length > 0) {
       return validationFailed(c, `Block "${block.id}" can't take this version`, continuity);
     }
 
-    const outcome = await binding.publish({ tenantId, projectId: projectId as ProjectId, block });
+    const outcome = await binding.publish({
+      tenantId,
+      projectId: projectId as ProjectId,
+      block: withCarriedSchema(latest, block),
+    });
     return published(c, outcome);
   });
 
@@ -243,7 +249,11 @@ function isBlockKind(value: string): value is BlockKind {
   return (BLOCK_KINDS as readonly string[]).includes(value);
 }
 
-/** A new version against the block's latest: same kind, and a settings block's schema holds. */
+/**
+ * A new version against the block's latest: the same kind, and a
+ * settings version without a schema of its own satisfies the schema it
+ * keeps (`carriedSchema`).
+ */
 function continuityIssues(
   latest: BlockRecord | null,
   block: BlockDefinition,
@@ -257,17 +267,32 @@ function continuityIssues(
       },
     ];
   }
-  if (
-    latest.kind === 'settings' &&
-    block.kind === 'settings' &&
-    latest.content.schema !== undefined
-  ) {
-    return settingsSchemaIssues(block.content.values, latest.content.schema).map((i) => ({
-      ...i,
-      message: `${i.message} (the schema of version ${latest.version})`,
-    }));
-  }
-  return [];
+  const carried = carriedSchema(latest, block);
+  if (block.kind !== 'settings' || carried === undefined) return [];
+  return settingsSchemaIssues(block.content.values, carried).map((i) => ({
+    ...i,
+    message: `${i.message} (the schema of version ${latest.version})`,
+  }));
+}
+
+/**
+ * The schema a settings version that gives none keeps: the latest
+ * version's. A version that gives a schema replaces it (`{}` drops the
+ * check on purpose).
+ */
+function carriedSchema(
+  latest: BlockRecord | null,
+  block: BlockDefinition,
+): Readonly<Record<string, unknown>> | undefined {
+  if (latest?.kind !== 'settings' || block.kind !== 'settings') return undefined;
+  return block.content.schema === undefined ? latest.content.schema : undefined;
+}
+
+/** The version as stored: with the schema it keeps, if any. */
+function withCarriedSchema(latest: BlockRecord | null, block: BlockDefinition): BlockDefinition {
+  const schema = carriedSchema(latest, block);
+  if (schema === undefined || block.kind !== 'settings') return block;
+  return { ...block, content: { ...block.content, schema } };
 }
 
 /** The response to a publish outcome. */

package/src/routes/deployments.ts

@@ -41,6 +41,7 @@ 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 RegistryReadOnly, refuseReadOnly } from '../registry-read-only.js';
 import type { SecretBinding } from '../secrets-binding.js';
 import type { SigningKeyBinding as SigningKeyRegistryBinding } from '../signing-key-binding.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
@@ -487,6 +488,11 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
     }
     const validated = validation.value;
 
+    // A read-only registry (under `kindgi dev`, the pack's files) takes
+    // nothing a deployment brings: refuse before any write.
+    const readOnly = readOnlyTarget(validated, bindings);
+    if (readOnly !== undefined) return refuseReadOnly(c, readOnly);
+
     // ---- Registry upserts (with rollback tracking) ----
     //
     // Agent-registry, flow-registry, tool-registry, and
@@ -1701,3 +1707,22 @@ export function sha256HexPrefixed(bytes: Uint8Array): string {
   const hex = createHash('sha256').update(bytes).digest('hex');
   return `sha256:${hex}`;
 }
+
+/** The first read-only registry a deployment would publish into, if any. */
+function readOnlyTarget(
+  validated: {
+    readonly tools: readonly unknown[];
+    readonly agents: readonly unknown[];
+    readonly flows: readonly unknown[];
+    readonly guardrails: readonly unknown[];
+  },
+  bindings: DeploymentsRouterBindings,
+): RegistryReadOnly | undefined {
+  const targets = [
+    [validated.tools, bindings.toolRegistry?.readOnly],
+    [validated.agents, bindings.agentRegistry?.readOnly],
+    [validated.flows, bindings.flowRegistry?.readOnly],
+    [validated.guardrails, bindings.guardrailRegistry?.readOnly],
+  ] as const;
+  return targets.find(([brought, readOnly]) => brought.length > 0 && readOnly !== undefined)?.[1];
+}