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

package/src/routes/eval-versions.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * A flow candidate's `versions`, checked against the flow version when
+ * the comparison starts: each id must be an agent or tool the flow uses,
+ * at a published version. Checked once, here, before any run exists: the
+ * runs apply them as given, on resume too.
+ */
+
+import type { AgentId } from '@kindgi/agents';
+import { type FlowVersionOverrides, overridableRefs } from '@kindgi/flow';
+import type { FlowId, Semver, TenantId, ToolId } from '@kindgi/types';
+
+import type { AgentRegistryBinding } from '../agent-binding.js';
+import type { FlowRegistryBinding } from '../flow-binding.js';
+import type { ToolRegistryBinding } from '../tool-binding.js';
+
+/** Where the check reads the flow version and the agents' and tools' versions. */
+export interface FlowVersionsCheck {
+  readonly flows: FlowRegistryBinding;
+  readonly agents?: AgentRegistryBinding;
+  readonly tools?: ToolRegistryBinding;
+}
+
+export interface VersionsIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+/** A JSON Pointer token: `~` and `/` escaped. */
+const token = (id: string): string => id.replaceAll('~', '~0').replaceAll('/', '~1');
+
+async function agentIssues(
+  check: FlowVersionsCheck,
+  tenantId: TenantId,
+  label: string,
+  used: ReadonlySet<string>,
+  overrides: Readonly<Record<string, string>>,
+): Promise<VersionsIssue[]> {
+  const issues: VersionsIssue[] = [];
+  for (const [id, version] of Object.entries(overrides)) {
+    const path = `/versions/agents/${token(id)}`;
+    if (!used.has(id)) {
+      issues.push({ path, message: `flow ${label} doesn't use agent ${id}` });
+      continue;
+    }
+    const found = await check.agents?.getVersion({
+      tenantId,
+      agentId: id as AgentId,
+      version: version as Semver,
+    });
+    if (found === null) issues.push({ path, message: `agent ${id} has no version ${version}` });
+    else if (found?.unregisteredAt !== undefined) {
+      issues.push({ path, message: `agent ${id} ${version} is unregistered` });
+    }
+  }
+  return issues;
+}
+
+async function toolIssues(
+  check: FlowVersionsCheck,
+  tenantId: TenantId,
+  label: string,
+  used: ReadonlySet<string>,
+  overrides: Readonly<Record<string, string>>,
+): Promise<VersionsIssue[]> {
+  const issues: VersionsIssue[] = [];
+  for (const [id, version] of Object.entries(overrides)) {
+    const path = `/versions/tools/${token(id)}`;
+    if (!used.has(id)) {
+      issues.push({ path, message: `flow ${label} doesn't use tool ${id}` });
+      continue;
+    }
+    const found = await check.tools?.getVersion({
+      tenantId,
+      toolId: id as ToolId,
+      version: version as Semver,
+    });
+    if (found === null) issues.push({ path, message: `tool ${id} has no version ${version}` });
+  }
+  return issues;
+}
+
+/**
+ * What's wrong with a flow candidate's `versions`, one issue per id; none
+ * when they fit. Without an agent or tool registry, those versions'
+ * existence isn't checked (the runs refuse an unpublished one).
+ */
+export async function checkFlowVersions(
+  check: FlowVersionsCheck,
+  tenantId: TenantId,
+  flowRef: { readonly flowId: string; readonly version: string },
+  versions: FlowVersionOverrides,
+): Promise<readonly VersionsIssue[]> {
+  const label = `${flowRef.flowId} ${flowRef.version}`;
+  const flow = await check.flows.getVersion({
+    tenantId,
+    flowId: flowRef.flowId as FlowId,
+    version: flowRef.version,
+  });
+  if (flow === null) {
+    return [{ path: '/flowRef/version', message: `flow ${label} isn't registered` }];
+  }
+  const refs = overridableRefs(flow);
+  return [
+    ...(await agentIssues(check, tenantId, label, new Set(refs.agents), versions.agents ?? {})),
+    ...(await toolIssues(check, tenantId, label, new Set(refs.tools), versions.tools ?? {})),
+  ];
+}

package/src/routes/flows.ts

@@ -12,7 +12,9 @@ import type { UnpinnableRef } from '../agent-pins.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { FlowRegistryBinding, FlowVersionRecord } from '../flow-binding.js';
 import { resolveFlowPins } from '../flow-pins.js';
+import type { LiveVersionBinding } from '../live-version-binding.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';
@@ -36,18 +38,26 @@ import { parseScopeParams } from './scope-params.js';
  * `/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.
+ * pinned: each tool it runs resolves once, at publish, to its latest
+ * version, and each agent it runs at no named version to what a run in
+ * the flow's project would get, its live version there with
+ * `pinning.live`, else its latest. Every run of that version uses those
+ * (`pins`, see `resolveFlowPins`); one with no published version refuses
+ * the publish. Without `pinning`, versions carry no pins and bind the
+ * latest versions per run.
  */
 export function flowsRouter(
   binding: FlowRegistryBinding,
   authorizer?: Authorizer,
-  pinning?: { readonly tools: ToolRegistryBinding; readonly agents: AgentRegistryBinding },
+  pinning?: FlowPinning,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  // A read-only registry (under `kindgi dev`, the pack's files) refuses
+  // every write before anything else runs.
+  r.use(
+    '*',
+    refuseWritesWhenReadOnly(() => binding.readOnly),
+  );
 
   // Authorization — mirrors agents 1:1. Check the resource directly;
   // permissions cascade from the parent project because publish writes
@@ -293,7 +303,7 @@ export function flowsRouter(
     // 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);
+    const pinned = await pinFlow(pinning, tenantId, projectId, loaded.value);
     if (pinned.kind === 'unpinnable') {
       c.status(statusFor('validation-failed') as never);
       return c.json(toWireError(unpinnableFlow(loaded.value, pinned.issues), requestId));
@@ -408,19 +418,32 @@ export function flowsRouter(
   return r;
 }
 
+/** The registries a published flow version is pinned against. */
+export interface FlowPinning {
+  readonly tools: ToolRegistryBinding;
+  readonly agents: AgentRegistryBinding;
+  /** The agents' live versions: an agent step pins the one live for the flow's project. */
+  readonly live?: LiveVersionBinding;
+}
+
 /** 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,
+  pinning: FlowPinning | undefined,
   tenantId: TenantId,
+  projectId: ProjectId,
   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);
+  const resolved = await resolveFlowPins(
+    pinning.tools,
+    pinning.agents,
+    tenantId,
+    flow,
+    pinning.live !== undefined ? { binding: pinning.live, projectId } : undefined,
+  );
   if (resolved.kind === 'unpinnable') return resolved;
   return {
     kind: 'ok',

package/src/routes/gate-policies.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Context, Hono } from 'hono';
+
+import { ref } from '@kindgi/authz';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { GatePolicyBinding, GatePolicyError } from '../gate-policy-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+import { scopeFromQuery } from './agent-releases.js';
+import { parseGatePolicySpec } from './gate-policy-spec.js';
+import { serializeGatePolicy } from './gate-policy-wire.js';
+import { parseLiveScopeBody } from './live-scope-wire.js';
+import { clampLimit } from './pagination.js';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+
+/**
+ * Gate policies (evals step 4b): what a promotion of an agent must show
+ * before a version goes live for a scope. The same registry shape as
+ * retention policies:
+ *   GET  /                                      each policy's latest active version (?agentId=, scope)
+ *   GET  /:policyId                             its latest active version
+ *   GET  /:policyId/versions[/:version]         every version, or one
+ *   POST /                                      publish {id, version, agentId, scope, spec, description?}
+ *   POST /:policyId/versions/:version/unregister|reinstate
+ *
+ * Writes need `admin` on the tenant: whoever may promote mustn't be able
+ * to loosen the gate on their own promotion.
+ */
+export function gatePoliciesRouter(
+  binding: GatePolicyBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  if (authorizer !== undefined) {
+    r.use('*', async (c, next) => {
+      if (c.req.method !== 'POST') return next();
+      const tenantId = c.get('tenantId') as unknown as string;
+      return authorizer.authorize('admin', () => ref('tenant', tenantId))(c, next);
+    });
+  }
+
+  r.get('/', async (c) => {
+    const requestId = c.get('requestId');
+    const scope = scopeFromQuery((n) => c.req.query(n), c.req.queries('segment') ?? []);
+    if (scope.kind === 'err') return badInput(c, requestId, scope.message);
+    const agentId = c.req.query('agentId');
+    const cursor = c.req.query('cursor');
+    const page = await binding.list({
+      tenantId: c.get('tenantId') as TenantId,
+      limit: clampLimit(c.req.query('limit')),
+      ...(agentId !== undefined && agentId.length > 0 && { agentId }),
+      ...(scope.scope !== undefined && { scope: scope.scope }),
+      ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor as Cursor }),
+    });
+    return c.json({
+      data: page.data.map(serializeGatePolicy),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  r.get('/:policyId', async (c) => {
+    const found = await binding.get({
+      tenantId: c.get('tenantId') as TenantId,
+      id: c.req.param('policyId'),
+    });
+    if (found === null) return notFound(c, c.req.param('policyId'));
+    return c.json(serializeGatePolicy(found));
+  });
+
+  r.get('/:policyId/versions', async (c) => {
+    const versions = await binding.listVersions({
+      tenantId: c.get('tenantId') as TenantId,
+      id: c.req.param('policyId'),
+    });
+    if (versions.length === 0) return notFound(c, c.req.param('policyId'));
+    return c.json({ data: versions.map(serializeGatePolicy), hasMore: false });
+  });
+
+  r.get('/:policyId/versions/:version', async (c) => {
+    const found = await binding.getVersion({
+      tenantId: c.get('tenantId') as TenantId,
+      id: c.req.param('policyId'),
+      version: c.req.param('version'),
+    });
+    if (found === null) {
+      return notFound(c, c.req.param('policyId'), c.req.param('version'));
+    }
+    return c.json(serializeGatePolicy(found));
+  });
+
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return badInput(c, requestId, 'Request body must be a JSON object');
+    }
+    const parsed = parsePublishBody(body);
+    if (parsed.kind === 'err') {
+      c.status(statusFor('validation-failed') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'validation-failed',
+            message: `The gate policy isn't valid: ${parsed.issues.map((i) => `${i.path}: ${i.message}`).join('; ')}`,
+            issues: parsed.issues,
+          },
+          requestId,
+        ),
+      );
+    }
+    const outcome = await binding.publish({
+      tenantId: c.get('tenantId') as TenantId,
+      ...parsed.value,
+    });
+    if (outcome.kind === 'err') return failed(c, requestId, outcome.error);
+    c.status(201);
+    return c.json(serializeGatePolicy(outcome.value));
+  });
+
+  for (const action of ['unregister', 'reinstate'] as const) {
+    r.post(`/:policyId/versions/:version/${action}`, async (c) => {
+      const outcome = await binding[action]({
+        tenantId: c.get('tenantId') as TenantId,
+        id: c.req.param('policyId'),
+        version: c.req.param('version'),
+      });
+      if (outcome.kind === 'err') return failed(c, c.get('requestId'), outcome.error);
+      return c.json(serializeGatePolicy(outcome.value));
+    });
+  }
+
+  return r;
+}
+
+type Ctx = Context<AppEnv>;
+
+function badInput(c: Ctx, requestId: string, message: string) {
+  c.status(statusFor('bad-input') as never);
+  return c.json(toWireError({ code: 'bad-input', message }, requestId));
+}
+
+function notFound(c: Ctx, policyId: string, version?: string) {
+  c.status(statusFor('gate-policy-not-found') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'gate-policy-not-found',
+        message:
+          version === undefined
+            ? `No active gate policy "${policyId}"`
+            : `Gate policy "${policyId}" has no version ${version}`,
+        policyId,
+      },
+      c.get('requestId'),
+    ),
+  );
+}
+
+function failed(c: Ctx, requestId: string, error: GatePolicyError) {
+  c.status(statusFor(error.code) as never);
+  return c.json(toWireError({ ...error }, requestId));
+}
+
+type Issue = { readonly path: string; readonly message: string };
+
+function parsePublishBody(body: unknown):
+  | {
+      kind: 'ok';
+      value: Omit<Parameters<GatePolicyBinding['publish']>[0], 'tenantId'>;
+    }
+  | { kind: 'err'; issues: readonly Issue[] } {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { kind: 'err', issues: [{ path: '', message: 'the body must be a JSON object' }] };
+  }
+  const b = body as Record<string, unknown>;
+  const issues: Issue[] = [];
+  for (const key of Object.keys(b)) {
+    if (!['id', 'version', 'agentId', 'scope', 'spec', 'description'].includes(key)) {
+      issues.push({ path: `/${key}`, message: `\`${key}\` isn't a gate policy field` });
+    }
+  }
+  if (typeof b.id !== 'string' || !ID_RE.test(b.id)) {
+    issues.push({
+      path: '/id',
+      message:
+        '`id` must be lowercase letters, digits, `.`, `_` or `-` (e.g. "acme.drafting-prod")',
+    });
+  }
+  if (typeof b.version !== 'string' || !SEMVER_RE.test(b.version)) {
+    issues.push({ path: '/version', message: '`version` must be a semver version (e.g. "1.0.0")' });
+  }
+  if (typeof b.agentId !== 'string' || b.agentId === '') {
+    issues.push({ path: '/agentId', message: '`agentId` is required: the agent the policy gates' });
+  }
+  const scope = parseLiveScopeBody(b.scope);
+  if (scope.kind === 'err') issues.push({ path: '/scope', message: scope.message });
+  const spec = parseGatePolicySpec(b.spec);
+  if (spec.kind === 'err') issues.push(...spec.issues);
+  if (b.description !== undefined && (typeof b.description !== 'string' || b.description === '')) {
+    issues.push({ path: '/description', message: '`description` must be a non-empty string' });
+  }
+  if (issues.length > 0 || scope.kind === 'err' || spec.kind === 'err') {
+    return { kind: 'err', issues };
+  }
+  return {
+    kind: 'ok',
+    value: {
+      id: b.id as string,
+      version: b.version as string,
+      agentId: b.agentId as string,
+      scope: scope.scope,
+      spec: spec.spec,
+      ...(typeof b.description === 'string' && { description: b.description }),
+    },
+  };
+}

package/src/routes/gate-policy-spec.ts

@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { REVIEWER_ROLE_RANK, type ReviewerRole } from '@kindgi/authz';
+
+import { GATE_METRICS, type GateMetricSpec, type GatePolicySpec } from '../gate-policy-binding.js';
+
+/**
+ * A gate policy's `spec`, checked strictly: an unknown key is an issue, so
+ * a typo can't leave a check silently off.
+ */
+
+export interface SpecIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+type Raw = Readonly<Record<string, unknown>>;
+
+const REVIEWER_ROLES = Object.keys(REVIEWER_ROLE_RANK) as readonly ReviewerRole[];
+
+const isObject = (v: unknown): v is Raw => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Keys the policy may not use yet, with why. */
+const LATER: Readonly<Record<string, string>> = {
+  '/spec/approvals/count': 'one reviewer decides a promotion today; leave `count` out',
+  '/spec/approvals/forRollback': "rollbacks aren't gated yet; leave `forRollback` out",
+};
+
+function unknownKeys(raw: Raw, allowed: readonly string[], at: string, issues: SpecIssue[]) {
+  for (const key of Object.keys(raw)) {
+    if (allowed.includes(key)) continue;
+    const path = `${at}/${key}`;
+    issues.push({
+      path,
+      message:
+        LATER[path] ??
+        `\`${key}\` isn't a gate policy setting here (expected: ${allowed.join(', ')})`,
+    });
+  }
+}
+
+/** A number in [min, max], when present. */
+function num(
+  raw: Raw,
+  key: string,
+  at: string,
+  issues: SpecIssue[],
+  opts: { min: number; max?: number; integer?: boolean; positive?: boolean },
+): number | undefined {
+  const v = raw[key];
+  if (v === undefined) return undefined;
+  const ok =
+    typeof v === 'number' &&
+    Number.isFinite(v) &&
+    v >= opts.min &&
+    (opts.max === undefined || v <= opts.max) &&
+    (opts.integer !== true || Number.isInteger(v)) &&
+    (opts.positive !== true || v > 0);
+  if (!ok) {
+    const range = opts.max === undefined ? `at least ${opts.min}` : `${opts.min} to ${opts.max}`;
+    issues.push({
+      path: `${at}/${key}`,
+      message: `\`${key}\` must be ${opts.integer === true ? 'a whole number' : 'a number'}, ${opts.positive === true ? 'above 0' : range}`,
+    });
+    return undefined;
+  }
+  return v as number;
+}
+
+function bool(raw: Raw, key: string, at: string, issues: SpecIssue[]): boolean | undefined {
+  const v = raw[key];
+  if (v === undefined) return undefined;
+  if (typeof v !== 'boolean') {
+    issues.push({ path: `${at}/${key}`, message: `\`${key}\` must be true or false` });
+    return undefined;
+  }
+  return v;
+}
+
+function block(raw: Raw, key: string, issues: SpecIssue[]): Raw | undefined {
+  const v = raw[key];
+  if (v === undefined) return undefined;
+  if (!isObject(v)) {
+    issues.push({ path: `/spec/${key}`, message: `\`${key}\` must be an object` });
+    return undefined;
+  }
+  return v;
+}
+
+export function parseGatePolicySpec(
+  raw: unknown,
+): { kind: 'ok'; spec: GatePolicySpec } | { kind: 'err'; issues: readonly SpecIssue[] } {
+  if (!isObject(raw)) {
+    return { kind: 'err', issues: [{ path: '/spec', message: '`spec` must be an object' }] };
+  }
+  const issues: SpecIssue[] = [];
+  unknownKeys(
+    raw,
+    ['comparison', 'evidence', 'metrics', 'replay', 'approvals', 'onlyRestrictedClasses'],
+    '/spec',
+    issues,
+  );
+  const spec: {
+    -readonly [K in keyof GatePolicySpec]: GatePolicySpec[K];
+  } = {};
+
+  const comparison = block(raw, 'comparison', issues);
+  if (comparison !== undefined) {
+    const at = '/spec/comparison';
+    unknownKeys(comparison, ['maxAgeHours', 'suite'], at, issues);
+    const maxAgeHours = num(comparison, 'maxAgeHours', at, issues, { min: 0, positive: true });
+    let suite: { id: string; version?: string } | undefined;
+    if (comparison.suite !== undefined) {
+      const s = comparison.suite;
+      if (!isObject(s) || typeof s.id !== 'string' || s.id === '') {
+        issues.push({ path: `${at}/suite`, message: '`suite` must be `{ id, version? }`' });
+      } else {
+        unknownKeys(s, ['id', 'version'], `${at}/suite`, issues);
+        if (s.version !== undefined && (typeof s.version !== 'string' || s.version === '')) {
+          issues.push({ path: `${at}/suite/version`, message: '`version` must be a version' });
+        }
+        suite = { id: s.id, ...(typeof s.version === 'string' && { version: s.version }) };
+      }
+    }
+    spec.comparison = {
+      ...(maxAgeHours !== undefined && { maxAgeHours }),
+      ...(suite !== undefined && { suite }),
+    };
+  }
+
+  const evidence = block(raw, 'evidence', issues);
+  if (evidence !== undefined) {
+    const at = '/spec/evidence';
+    unknownKeys(evidence, ['minCases', 'minWeight'], at, issues);
+    const minCases = num(evidence, 'minCases', at, issues, { min: 0, integer: true });
+    const minWeight = num(evidence, 'minWeight', at, issues, { min: 0 });
+    spec.evidence = {
+      ...(minCases !== undefined && { minCases }),
+      ...(minWeight !== undefined && { minWeight }),
+    };
+  }
+
+  if (raw.metrics !== undefined) {
+    if (!Array.isArray(raw.metrics)) {
+      issues.push({ path: '/spec/metrics', message: '`metrics` must be a list' });
+    } else {
+      const metrics: GateMetricSpec[] = [];
+      const seen = new Set<string>();
+      raw.metrics.forEach((m: unknown, i: number) => {
+        const at = `/spec/metrics/${i}`;
+        const before = issues.length;
+        if (!isObject(m)) {
+          issues.push({ path: at, message: 'each metric must be an object' });
+          return;
+        }
+        unknownKeys(m, ['name', 'k', 'minCandidate', 'maxDrop'], at, issues);
+        const name = m.name;
+        if (typeof name !== 'string' || !(GATE_METRICS as readonly string[]).includes(name)) {
+          issues.push({
+            path: `${at}/name`,
+            message: `\`name\` must be one of: ${GATE_METRICS.join(', ')}`,
+          });
+          return;
+        }
+        if (seen.has(name)) {
+          issues.push({ path: `${at}/name`, message: `\`${name}\` is gated twice` });
+          return;
+        }
+        seen.add(name);
+        if (m.k !== undefined && name !== 'weightedPrecisionAtK') {
+          issues.push({ path: `${at}/k`, message: '`k` applies to `weightedPrecisionAtK` only' });
+        }
+        const k = num(m, 'k', at, issues, { min: 1, max: 100, integer: true });
+        const minCandidate = num(m, 'minCandidate', at, issues, { min: 0, max: 1 });
+        const maxDrop = num(m, 'maxDrop', at, issues, { min: 0, max: 1 });
+        if (minCandidate === undefined && maxDrop === undefined && issues.length === before) {
+          issues.push({
+            path: at,
+            message: `\`${name}\` needs \`minCandidate\`, \`maxDrop\` or both: what it must reach`,
+          });
+        }
+        metrics.push({
+          name: name as GateMetricSpec['name'],
+          ...(k !== undefined && { k }),
+          ...(minCandidate !== undefined && { minCandidate }),
+          ...(maxDrop !== undefined && { maxDrop }),
+        });
+      });
+      spec.metrics = metrics;
+    }
+  }
+
+  const replay = block(raw, 'replay', issues);
+  if (replay !== undefined) {
+    const at = '/spec/replay';
+    const knobs = ['maxDiverged', 'maxErrors', 'maxRefusedWrites', 'maxStopped'] as const;
+    unknownKeys(replay, knobs, at, issues);
+    const out: { -readonly [K in (typeof knobs)[number]]?: number } = {};
+    for (const knob of knobs) {
+      const v = num(replay, knob, at, issues, { min: 0, integer: true });
+      if (v !== undefined) out[knob] = v;
+    }
+    spec.replay = out;
+  }
+
+  const approvals = block(raw, 'approvals', issues);
+  if (approvals !== undefined) {
+    const at = '/spec/approvals';
+    unknownKeys(approvals, ['role', 'separateApprover'], at, issues);
+    const role = approvals.role;
+    if (role !== undefined && !(REVIEWER_ROLES as readonly unknown[]).includes(role)) {
+      issues.push({
+        path: `${at}/role`,
+        message: `\`role\` must be one of: ${REVIEWER_ROLES.join(', ')}`,
+      });
+    }
+    const separateApprover = bool(approvals, 'separateApprover', at, issues);
+    spec.approvals = {
+      ...(typeof role === 'string' && { role: role as ReviewerRole }),
+      ...(separateApprover !== undefined && { separateApprover }),
+    };
+  }
+
+  const onlyRestricted = bool(raw, 'onlyRestrictedClasses', '/spec', issues);
+  if (onlyRestricted !== undefined) spec.onlyRestrictedClasses = onlyRestricted;
+
+  return issues.length > 0 ? { kind: 'err', issues } : { kind: 'ok', spec };
+}

package/src/routes/gate-policy-wire.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { GatePolicy } from '../gate-policy-binding.js';
+import { liveScopeToWire } from './live-scope-wire.js';
+
+export function serializeGatePolicy(p: GatePolicy): Record<string, unknown> {
+  return {
+    id: p.id,
+    version: p.version,
+    agentId: p.agentId,
+    scope: liveScopeToWire(p.scope),
+    spec: p.spec,
+    ...(p.description !== undefined && { description: p.description }),
+    createdAt: p.createdAt as unknown as string,
+    ...(p.unregisteredAt !== undefined && {
+      unregisteredAt: p.unregisteredAt as unknown as string,
+    }),
+  };
+}