@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/src/routes/proposals.ts

@@ -3,157 +3,159 @@
 
 import { type Context, Hono } from 'hono';
 
-import type {
-  AgentId,
-  Cursor,
-  FixProposalId,
-  SupervisorId,
-  TenantId,
-  Timestamp,
-} from '@kindgi/types';
+import type { AgentId } from '@kindgi/agents';
+import { type Action, ref } from '@kindgi/authz';
+import type { Cursor, FixProposalId, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { EvalComparison } from '../eval-run-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import {
+  type ProposalFacts,
+  type ProposalService,
+  type ProposalServiceDeps,
+  type ProposalServiceError,
+  createProposalService,
+  proposalNotFound,
+} from '../proposal-service.js';
+import {
+  FIX_PROPOSAL_STATUSES,
+  type FixProposalStatus,
+  type ProposalEvaluationOutcome,
+} from '../proposal-status.js';
 import type {
-  FixProposal,
-  FixProposalStatus,
-  PassCriterion,
-  PatternRef,
+  ProposalObjective,
+  ProposalTier,
   ProposedChange,
-  SupervisorBinding,
+  StoredProposal,
 } from '../supervisor-binding.js';
 import type { AppEnv } from '../types.js';
+import { actorOf, promotionResponse, scopeFromQuery } from './agent-releases.js';
+import { parseComparison } from './eval-comparison.js';
+import { liveScopeToWire, parseLiveScopeBody } from './live-scope-wire.js';
 import { clampLimit } from './pagination.js';
-import { parseScopeParams } from './scope-params.js';
-
-const FIX_PROPOSAL_STATUSES: ReadonlySet<FixProposalStatus> = new Set([
-  'draft',
-  'dry-running',
-  'dry-run-passed',
-  'dry-run-failed',
-  'proposed-for-review',
-  'approved',
-  'rejected',
-  'applied',
-  'rolled-back',
-  'withdrawn',
-]);
-
-const PROPOSAL_TIERS: ReadonlySet<ProposedChange['tier']> = new Set([
-  'prompt',
-  'retrieval',
-  'tool-config',
-]);
-
-const REVIEWER_ROLES: ReadonlySet<'standard' | 'senior' | 'admin'> = new Set([
-  'standard',
-  'senior',
-  'admin',
-]);
+
+/** What the proposal lifecycle runs on besides its own store. */
+export type ProposalsRouteDeps = Omit<ProposalServiceDeps, 'store'>;
+
+const TIERS: readonly ProposalTier[] = ['settings-block', 'prompt-block'];
+const OBJECTIVES: readonly ProposalObjective[] = ['weightedYesShare', 'weightedPrecisionAtK'];
+const MAX_TEXT = 2000;
+
+type Ctx = Context<AppEnv>;
 
 /**
- * Supervisor proposals resource. Ships the full self-fix lifecycle
- * over HTTP: draft → dry-run → submit-review → apply / rollback /
- * withdraw — the complete supervisor loop.
+ * Improvement proposals (`/v1/proposals`): a change to one data block an
+ * agent version pins (new settings values, or a new prompt template),
+ * for one live scope, taken through the same comparison, gate and
+ * promotion as any other version (`createProposalService`).
  *
- * Persistence + runtime wiring is caller-plugged via
- * `SupervisorBinding` — the API package doesn't own supervisor
- * runtime, agent registry, HITL wiring, or eval invocation.
+ *   GET  /                 list (statuses derived): by agent, tier, status and live scope
+ *   GET  /:id              one
+ *   POST /                 a hand-written proposal (a draft)
+ *   POST /:id/evaluate     publish the block version and derive the agent
+ *                          version (inert until promoted), then compare it
+ *                          on a test set (202)
+ *   POST /:id/request      a gated promotion of the candidate for the scope
+ *                          (201 promoted, 202 in review, 422 gate-failed)
+ *   POST /:id/rollback     the scope goes back to what served it before
+ *   POST /:id/withdraw     closed by a person
  *
- * `supervisorId` scoping: every route requires an `X-Supervisor-Id`
- * request header. Missing / empty → `400 supervisor-header-missing`.
- *
- * State transitions: attempts to advance a proposal from a status
- * the runtime won't accept (e.g., apply on a proposal still in
- * `dry-running`) surface as `409 proposal-invalid-state-transition`.
- * This is a caller/state conflict per `docs/API-ROUTE-CONVENTIONS.md`
- * §4.3 — the request was well-formed but the resource is not in
- * the required state.
+ * Authorized on the proposal's agent: reading is `read`, drafting,
+ * evaluating and withdrawing are `publish` (they make versions), and
+ * requesting and rolling back are `promote`. A proposal the caller can't
+ * read answers 404, as one that doesn't exist.
  */
-export function proposalsRouter(binding: SupervisorBinding): Hono<AppEnv> {
+export function proposalsRouter(
+  store: ProposalServiceDeps['store'],
+  deps: ProposalsRouteDeps,
+  authorizer?: Authorizer,
+  mount?: (r: Hono<AppEnv>, service: ProposalService) => void,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  const service = createProposalService({ ...deps, store });
+  // Routes mounted before `/:proposalId` (an improvement pass's `improve`).
+  mount?.(r, service);
+
+  /** `undefined` when allowed; else the 403. */
+  async function deny(c: Ctx, action: Action, agentId: string) {
+    if (authorizer === undefined) return undefined;
+    const decision = await authorizer.check(c, action, ref('agent', agentId));
+    if (decision.allowed) return undefined;
+    return fail(c, 'permission-denied', {
+      code: 'permission-denied',
+      message: `Permission denied: this needs ${action} on agent "${agentId}" (${decision.reason})`,
+    });
+  }
 
-  // ---------- supervisor-id gate for the whole resource ----------
-  r.use('*', async (c, next) => {
-    const requestId = c.get('requestId');
-    const supervisorId = c.req.header('x-supervisor-id');
-    if (supervisorId === undefined || supervisorId.length === 0) {
-      c.status(statusFor('supervisor-header-missing') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'supervisor-header-missing',
-            message:
-              'X-Supervisor-Id header is required on all /v1/proposals routes; supply the SupervisorId scoping the request.',
-          },
-          requestId,
-        ),
-      );
-    }
-    await next();
-    return;
-  });
-
-  // ---------- GET / (list, cursor-paginated) ----------
-  r.get('/', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const limit = clampLimit(c.req.query('limit'));
-
-    const cursorRaw = c.req.query('cursor');
-    const statusRaw = c.req.query('status');
-    const agentIdRaw = c.req.query('agentId');
-    const tierRaw = c.req.query('tier');
-
-    let status: FixProposalStatus | undefined;
-    if (statusRaw !== undefined && statusRaw.length > 0) {
-      if (!FIX_PROPOSAL_STATUSES.has(statusRaw as FixProposalStatus)) {
-        c.status(statusFor('bad-input') as never);
-        return c.json(
-          toWireError(
-            { code: 'bad-input', message: `Unknown \`status\` value: ${statusRaw}` },
-            requestId,
-          ),
-        );
-      }
-      status = statusRaw as FixProposalStatus;
-    }
+  /** The proposal, if it exists and the caller may read it (else the 404). */
+  async function load(c: Ctx): Promise<StoredProposal | Response> {
+    const proposalId = c.req.param('proposalId') ?? '';
+    const stored = await store.getProposal({
+      tenantId: c.get('tenantId') as TenantId,
+      proposalId: proposalId as FixProposalId,
+    });
+    const hidden =
+      stored !== null &&
+      authorizer !== undefined &&
+      !(await authorizer.can(c, 'read', ref('agent', stored.agentId as unknown as string)));
+    if (stored === null || hidden) return failWith(c, proposalNotFound(proposalId));
+    return stored;
+  }
 
-    let tier: ProposedChange['tier'] | undefined;
-    if (tierRaw !== undefined && tierRaw.length > 0) {
-      if (!PROPOSAL_TIERS.has(tierRaw as ProposedChange['tier'])) {
-        c.status(statusFor('bad-input') as never);
-        return c.json(
-          toWireError(
-            { code: 'bad-input', message: `Unknown \`tier\` value: ${tierRaw}` },
-            requestId,
-          ),
-        );
-      }
-      tier = tierRaw as ProposedChange['tier'];
-    }
+  async function answer(c: Ctx, stored: StoredProposal, status: 200 | 201 | 202 = 200) {
+    const f = await service.facts(c.get('tenantId') as TenantId)(stored);
+    c.status(status);
+    return c.json(serialize(stored, f));
+  }
 
-    const scopeParsed = parseScopeParams(c.req.query(), { tenantId });
-    if (scopeParsed.kind === 'err') {
-      c.status(statusFor('scope-invalid') as never);
-      return c.json(
-        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
-      );
-    }
+  /** Read the body and the proposal, and check the caller may `action` it. */
+  async function prepare(
+    c: Ctx,
+    action: Action,
+  ): Promise<{ body: Record<string, unknown>; proposal: StoredProposal } | Response> {
+    const body = await readBody(c);
+    if (body === undefined) return badInput(c, 'Request body must be a JSON object');
+    const proposal = await load(c);
+    if (proposal instanceof Response) return proposal;
+    const denied = await deny(c, action, proposal.agentId as unknown as string);
+    return denied ?? { body, proposal };
+  }
 
-    const page = await binding.listProposals({
+  // ---------- GET / ----------
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const status = c.req.query('status');
+    if (status !== undefined && !FIX_PROPOSAL_STATUSES.includes(status as FixProposalStatus)) {
+      return badInput(c, `Unknown \`status\`: ${status}`);
+    }
+    const tier = c.req.query('tier');
+    if (tier !== undefined && !TIERS.includes(tier as ProposalTier)) {
+      return badInput(c, `Unknown \`tier\`: ${tier} (one of ${TIERS.join(', ')})`);
+    }
+    const scope = scopeFromQuery((n) => c.req.query(n), c.req.queries('segment') ?? []);
+    if (scope.kind === 'err') return badInput(c, scope.message);
+    const agentId = c.req.query('agentId');
+    const cursor = c.req.query('cursor');
+    const page = await store.listProposals({
       tenantId,
-      supervisorId,
-      limit,
-      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
-      ...(status !== undefined && { status }),
-      ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw as AgentId }),
-      ...(tier !== undefined && { tier }),
-      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
-      ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+      limit: clampLimit(c.req.query('limit')),
+      ...(cursor !== undefined && cursor !== '' && { cursor: cursor as Cursor }),
+      ...(agentId !== undefined && agentId !== '' && { agentId: agentId as AgentId }),
+      ...(tier !== undefined && { tier: tier as ProposalTier }),
+      ...(scope.scope !== undefined && { liveScope: scope.scope }),
     });
+    const readable =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (p) =>
+            ref('agent', p.agentId as unknown as string),
+          );
+    const read = service.facts(tenantId);
+    const rows = await Promise.all(readable.map(async (p) => serialize(p, await read(p))));
     return c.json({
-      data: page.data.map(serializeProposal),
+      // A status filter applies after deriving, so a page can hold fewer rows than `limit`.
+      data: status === undefined ? rows : rows.filter((row) => row.status === status),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -161,559 +163,316 @@ export function proposalsRouter(binding: SupervisorBinding): Hono<AppEnv> {
 
   // ---------- GET /:proposalId ----------
   r.get('/:proposalId', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const proposalId = c.req.param('proposalId') as FixProposalId;
-
-    const proposal = await binding.getProposal({ tenantId, supervisorId, proposalId });
-    if (proposal === null) {
-      return proposalNotFound(c, requestId, proposalId);
-    }
-    return c.json(serializeProposal(proposal));
+    const stored = await load(c);
+    if (stored instanceof Response) return stored;
+    return answer(c, stored);
   });
 
-  // ---------- POST / (draft) ----------
+  // ---------- POST / (a hand-written proposal) ----------
   r.post('/', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      return badInput(c, requestId, 'Request body must be valid JSON');
-    }
-    const parsed = parseDraftBody(body);
-    if (parsed.kind === 'err') {
-      return badInput(c, requestId, parsed.message);
-    }
-
-    const outcome = await binding.draftProposal({
-      tenantId,
-      supervisorId,
-      agentId: parsed.value.agentId,
-      agentVersion: parsed.value.agentVersion,
-      tier: parsed.value.tier,
-      change: parsed.value.change,
-      patternRefs: parsed.value.patternRefs,
-      hypothesis: parsed.value.hypothesis,
-      proposerRuleId: parsed.value.proposerRuleId,
+    const body = await readBody(c);
+    if (body === undefined) return badInput(c, 'Request body must be a JSON object');
+    const parsed = parseCreateBody(body);
+    if (typeof parsed === 'string') return badInput(c, parsed);
+    const denied = await deny(c, 'publish', parsed.agentId);
+    if (denied !== undefined) return denied;
+    const actor = actorOf(c);
+    const outcome = await service.draft({
+      tenantId: c.get('tenantId') as TenantId,
+      agentId: parsed.agentId,
+      fromVersion: parsed.fromVersion,
+      scope: parsed.scope,
+      tier: parsed.tier,
+      blockId: parsed.blockId,
+      content: parsed.content,
+      hypothesis: parsed.hypothesis,
+      ...(parsed.judgmentIds !== undefined && { evidence: { judgmentIds: parsed.judgmentIds } }),
+      drafter: { kind: 'person', by: `${actor.kind}:${actor.id}` },
     });
-    // Both `ok` and `dedup` return 201 — the caller ends up with a
-    // proposal id it can advance. Signal dedup via a header so
-    // consumers that care can distinguish (mirrors the
-    // X-Idempotent-Replay pattern from the idempotency middleware).
-    if (outcome.kind === 'dedup') {
+    if (outcome.kind === 'err') return failWith(c, outcome.error);
+    if (outcome.value.deduped) {
       c.header('X-Proposal-Deduped', 'true');
+      return answer(c, outcome.value.proposal);
     }
-    c.status(201);
-    return c.json(serializeProposal(outcome.proposal));
+    return answer(c, outcome.value.proposal, 201);
   });
 
-  // ---------- POST /:proposalId/dry-run ----------
-  r.post('/:proposalId/dry-run', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const proposalId = c.req.param('proposalId') as FixProposalId;
-
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      return badInput(c, requestId, 'Request body must be valid JSON');
-    }
-    const parsed = parseDryRunBody(body);
-    if (parsed.kind === 'err') {
-      return badInput(c, requestId, parsed.message);
-    }
-
-    const outcome = await binding.dryRunProposal({
-      tenantId,
-      supervisorId,
-      proposalId,
-      datasetId: parsed.value.datasetId,
-      datasetVersion: parsed.value.datasetVersion,
-      criterion: parsed.value.criterion,
-    });
-    if (outcome.kind === 'not-found') {
-      return proposalNotFound(c, requestId, proposalId);
-    }
-    if (outcome.kind === 'invalid-transition') {
-      return invalidTransition(c, requestId, outcome.proposalId, outcome.from, outcome.to);
-    }
-    if (outcome.kind === 'runtime-error') {
-      return runtimeError(c, requestId, outcome.code, outcome.message);
-    }
-    return c.json({
-      proposal: serializeProposal(outcome.proposal),
-      passed: outcome.passed,
-    });
-  });
-
-  // ---------- POST /:proposalId/submit-review ----------
-  r.post('/:proposalId/submit-review', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const proposalId = c.req.param('proposalId') as FixProposalId;
-
-    // Body is optional — every field on submit-review is an override.
-    let body: unknown = {};
-    try {
-      const raw = await c.req.text();
-      if (raw.length > 0) body = JSON.parse(raw);
-    } catch {
-      return badInput(c, requestId, 'Request body must be valid JSON');
-    }
-    const parsed = parseSubmitReviewBody(body);
-    if (parsed.kind === 'err') {
-      return badInput(c, requestId, parsed.message);
-    }
-
-    const outcome = await binding.submitReview({
-      tenantId,
-      supervisorId,
-      proposalId,
-      ...(parsed.value.requiredRole !== undefined && { requiredRole: parsed.value.requiredRole }),
-      ...(parsed.value.expiresAt !== undefined && { expiresAt: parsed.value.expiresAt }),
-    });
-    if (outcome.kind === 'not-found') {
-      return proposalNotFound(c, requestId, proposalId);
-    }
-    if (outcome.kind === 'invalid-transition') {
-      return invalidTransition(c, requestId, outcome.proposalId, outcome.from, outcome.to);
-    }
-    if (outcome.kind === 'ground-layer-violation') {
-      c.status(statusFor('ground-layer-violation') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'ground-layer-violation',
-            message: `Proposal ${outcome.proposalId as unknown as string} violated ground guardrail ${outcome.guardrailId}: ${outcome.reason}`,
-            proposalId: outcome.proposalId as unknown as string,
-            guardrailId: outcome.guardrailId,
-            reason: outcome.reason,
-          },
-          requestId,
-        ),
-      );
-    }
-    if (outcome.kind === 'runtime-error') {
-      return runtimeError(c, requestId, outcome.code, outcome.message);
-    }
-    return c.json({
-      proposal: serializeProposal(outcome.proposal),
-      approvalId: outcome.approvalId as unknown as string,
-      metaFix: outcome.metaFix,
+  // ---------- POST /:proposalId/evaluate ----------
+  r.post('/:proposalId/evaluate', async (c) => {
+    const body = await readBody(c);
+    if (body === undefined) return badInput(c, 'Request body must be a JSON object');
+    const parsed = parseEvaluateBody(body);
+    if (typeof parsed === 'string') return badInput(c, parsed);
+    const ready = await prepare(c, 'publish');
+    if (ready instanceof Response) return ready;
+    const outcome = await service.evaluate({
+      tenantId: c.get('tenantId') as TenantId,
+      proposal: ready.proposal,
+      suiteId: parsed.suiteId,
+      objective: parsed.objective,
+      ...(parsed.comparison !== undefined && { comparison: parsed.comparison }),
+      actor: actorOf(c),
     });
+    if (outcome.kind === 'err') return failWith(c, outcome.error);
+    return answer(c, outcome.value, 202);
   });
 
-  // ---------- POST /:proposalId/apply ----------
-  r.post('/:proposalId/apply', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const proposalId = c.req.param('proposalId') as FixProposalId;
-
-    let body: unknown = {};
-    try {
-      const raw = await c.req.text();
-      if (raw.length > 0) body = JSON.parse(raw);
-    } catch {
-      return badInput(c, requestId, 'Request body must be valid JSON');
-    }
-    const parsed = parseApplyBody(body);
-    if (parsed.kind === 'err') {
-      return badInput(c, requestId, parsed.message);
-    }
-
-    const outcome = await binding.applyProposal({
-      tenantId,
-      supervisorId,
-      proposalId,
-      ...(parsed.value.newVersion !== undefined && { newVersion: parsed.value.newVersion }),
+  // ---------- POST /:proposalId/request ----------
+  r.post('/:proposalId/request', async (c) => {
+    const ready = await prepare(c, 'promote');
+    if (ready instanceof Response) return ready;
+    const reason = optionalText(ready.body, 'reason');
+    if (reason.kind === 'err') return badInput(c, reason.message);
+    const outcome = await service.request({
+      tenantId: c.get('tenantId') as TenantId,
+      proposal: ready.proposal,
+      actor: actorOf(c),
+      ...(reason.value !== undefined && { reason: reason.value }),
     });
-    if (outcome.kind === 'not-found') {
-      return proposalNotFound(c, requestId, proposalId);
-    }
-    if (outcome.kind === 'invalid-transition') {
-      return invalidTransition(c, requestId, outcome.proposalId, outcome.from, outcome.to);
+    if (outcome.kind === 'err') return failWith(c, outcome.error);
+    const { proposal, promotion } = outcome.value;
+    if (promotion.kind !== 'ok') return promotionResponse(c, promotion);
+    if (promotion.promotion.status === 'refused') {
+      return promotionResponse(c, promotion, { proposalId: proposal.id as unknown as string });
     }
-    if (outcome.kind === 'runtime-error') {
-      return runtimeError(c, requestId, outcome.code, outcome.message);
-    }
-    return c.json({
-      proposalId: outcome.proposalId as unknown as string,
-      appliedVersion: outcome.appliedVersion,
-      appliedAt: outcome.appliedAt as unknown as string,
-    });
+    return answer(c, proposal, promotion.promotion.status === 'pending-approval' ? 202 : 201);
   });
 
   // ---------- POST /:proposalId/rollback ----------
   r.post('/:proposalId/rollback', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const proposalId = c.req.param('proposalId') as FixProposalId;
-
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      return badInput(c, requestId, 'Request body must be valid JSON');
-    }
-    const parsed = parseReasonBody(body);
-    if (parsed.kind === 'err') {
-      return badInput(c, requestId, parsed.message);
-    }
-
-    const outcome = await binding.rollbackProposal({
-      tenantId,
-      supervisorId,
-      proposalId,
-      reason: parsed.value.reason,
-    });
-    if (outcome.kind === 'not-found') {
-      return proposalNotFound(c, requestId, proposalId);
-    }
-    if (outcome.kind === 'invalid-transition') {
-      return invalidTransition(c, requestId, outcome.proposalId, outcome.from, outcome.to);
-    }
-    if (outcome.kind === 'runtime-error') {
-      return runtimeError(c, requestId, outcome.code, outcome.message);
-    }
-    return c.json({
-      proposalId: outcome.proposalId as unknown as string,
-      rolledBackAt: outcome.rolledBackAt as unknown as string,
+    const ready = await prepare(c, 'promote');
+    if (ready instanceof Response) return ready;
+    const reason = optionalText(ready.body, 'reason');
+    if (reason.kind === 'err') return badInput(c, reason.message);
+    const outcome = await service.rollback({
+      tenantId: c.get('tenantId') as TenantId,
+      proposal: ready.proposal,
+      actor: actorOf(c),
+      ...(reason.value !== undefined && { reason: reason.value }),
     });
+    if (outcome.kind === 'err') return failWith(c, outcome.error);
+    return answer(c, outcome.value);
   });
 
   // ---------- POST /:proposalId/withdraw ----------
   r.post('/:proposalId/withdraw', async (c) => {
-    const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
-    const supervisorId = c.req.header('x-supervisor-id') as SupervisorId;
-    const proposalId = c.req.param('proposalId') as FixProposalId;
-
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      return badInput(c, requestId, 'Request body must be valid JSON');
-    }
-    const parsed = parseReasonBody(body);
-    if (parsed.kind === 'err') {
-      return badInput(c, requestId, parsed.message);
-    }
-
-    const outcome = await binding.withdrawProposal({
-      tenantId,
-      supervisorId,
-      proposalId,
-      reason: parsed.value.reason,
+    const ready = await prepare(c, 'publish');
+    if (ready instanceof Response) return ready;
+    const reason = optionalText(ready.body, 'reason');
+    if (reason.kind === 'err') return badInput(c, reason.message);
+    if (reason.value === undefined) {
+      return badInput(c, '`reason` is required: why it was withdrawn');
+    }
+    const outcome = await service.withdraw({
+      tenantId: c.get('tenantId') as TenantId,
+      proposal: ready.proposal,
+      actor: actorOf(c),
+      reason: reason.value,
     });
-    if (outcome.kind === 'not-found') {
-      return proposalNotFound(c, requestId, proposalId);
-    }
-    if (outcome.kind === 'invalid-transition') {
-      return invalidTransition(c, requestId, outcome.proposalId, outcome.from, outcome.to);
-    }
-    if (outcome.kind === 'runtime-error') {
-      return runtimeError(c, requestId, outcome.code, outcome.message);
-    }
-    return c.json(serializeProposal(outcome.proposal));
+    if (outcome.kind === 'err') return failWith(c, outcome.error);
+    return answer(c, outcome.value);
   });
 
   return r;
 }
 
-// -------------------- serialization --------------------
+// ---------- wire ----------
 
-function serializeProposal(p: FixProposal): Record<string, unknown> {
+function evaluationWire(
+  stored: NonNullable<StoredProposal['evaluation']>,
+  seen: ProposalEvaluationOutcome | null | undefined,
+): Record<string, unknown> {
+  if (seen === undefined || seen === null) return { ...stored };
+  return {
+    ...stored,
+    runStatus: seen.runStatus,
+    ...(seen.baseline !== undefined && { baseline: seen.baseline }),
+    ...(seen.candidate !== undefined && { candidate: seen.candidate }),
+    ...(seen.delta !== undefined && { delta: seen.delta }),
+    ...(seen.spread !== undefined && { spread: seen.spread }),
+    ...(seen.cases !== undefined && { cases: seen.cases }),
+    ...(seen.better !== undefined && { better: seen.better }),
+  };
+}
+
+export function serialize(p: StoredProposal, f: ProposalFacts): Record<string, unknown> {
+  const promotion = f.promotion ?? undefined;
   return {
     id: p.id as unknown as string,
-    tenantId: p.tenantId as unknown as string,
-    supervisorId: p.supervisorId as unknown as string,
     agentId: p.agentId as unknown as string,
-    agentVersion: p.agentVersion,
+    fromVersion: p.fromVersion,
+    scope: liveScopeToWire(p.scope),
     tier: p.tier,
     change: p.change,
-    patternRefs: p.patternRefs,
     hypothesis: p.hypothesis,
-    proposerRuleId: p.proposerRuleId,
-    status: p.status,
-    fingerprint: p.fingerprint,
-    ...(p.resolutionReason !== undefined && { resolutionReason: p.resolutionReason }),
-    ...(p.reviewApprovalId !== undefined && {
-      reviewApprovalId: p.reviewApprovalId as unknown as string,
+    ...(p.evidence !== undefined && { evidence: p.evidence }),
+    drafter: p.drafter,
+    status: f.status,
+    ...(p.candidate !== undefined && { candidate: p.candidate }),
+    ...(p.evaluation !== undefined && { evaluation: evaluationWire(p.evaluation, f.evaluation) }),
+    ...(promotion !== undefined && {
+      promotion: {
+        id: promotion.id,
+        status: promotion.status ?? 'promoted',
+        ...(promotion.approvalId !== undefined && { approvalId: promotion.approvalId }),
+        ...(f.liveNow !== undefined && { liveNow: f.liveNow }),
+      },
     }),
-    ...(p.appliedVersion !== undefined && { appliedVersion: p.appliedVersion }),
-    ...(p.appliedAt !== undefined && { appliedAt: p.appliedAt as unknown as string }),
-    ...(p.rolledBackAt !== undefined && { rolledBackAt: p.rolledBackAt as unknown as string }),
-    createdAt: p.createdAt as unknown as string,
-    updatedAt: p.updatedAt as unknown as string,
-    ...(p.resolvedAt !== undefined && { resolvedAt: p.resolvedAt as unknown as string }),
+    ...(p.rolledBack !== undefined && { rolledBack: p.rolledBack }),
+    ...(p.withdrawn !== undefined && { withdrawn: p.withdrawn }),
+    createdAt: p.createdAt,
+    updatedAt: p.updatedAt,
   };
 }
 
-// -------------------- error helpers --------------------
+// ---------- parsing ----------
 
-type Ctx = Context<AppEnv>;
-
-function badInput(c: Ctx, requestId: string, message: string): Response {
-  c.status(statusFor('bad-input') as never);
-  return c.json(toWireError({ code: 'bad-input', message }, requestId));
+interface CreateBody {
+  readonly agentId: string;
+  readonly fromVersion: string;
+  readonly scope: StoredProposal['scope'];
+  readonly tier: ProposalTier;
+  readonly blockId: string;
+  readonly content: ProposedChange['change']['content'];
+  readonly hypothesis: string;
+  readonly judgmentIds?: readonly string[];
 }
 
-function proposalNotFound(c: Ctx, requestId: string, proposalId: FixProposalId): Response {
-  c.status(statusFor('proposal-not-found') as never);
-  return c.json(
-    toWireError(
-      {
-        code: 'proposal-not-found',
-        message: `No proposal with id "${proposalId as unknown as string}"`,
-        proposalId: proposalId as unknown as string,
-      },
-      requestId,
-    ),
-  );
+function obj(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
 }
 
-function invalidTransition(
-  c: Ctx,
-  requestId: string,
-  proposalId: FixProposalId,
-  from: FixProposalStatus,
-  to: FixProposalStatus,
-): Response {
-  c.status(statusFor('proposal-invalid-state-transition') as never);
-  return c.json(
-    toWireError(
-      {
-        code: 'proposal-invalid-state-transition',
-        message: `Cannot transition proposal ${proposalId as unknown as string} from ${from} to ${to}`,
-        proposalId: proposalId as unknown as string,
-        from,
-        to,
-      },
-      requestId,
-    ),
-  );
+function nonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '' && value.length <= MAX_TEXT;
 }
 
-function runtimeError(c: Ctx, requestId: string, code: string, message: string): Response {
-  c.status(statusFor(code) as never);
-  return c.json(toWireError({ code, message }, requestId));
+function parseContent(tier: ProposalTier, raw: unknown): string | undefined {
+  const content = obj(raw);
+  const keys = content === undefined ? [] : Object.keys(content);
+  if (tier === 'settings-block') {
+    return content !== undefined && obj(content.values) !== undefined && keys.length === 1
+      ? undefined
+      : '`change.content` for a settings block is { values: { … } } (the schema carries over)';
+  }
+  return content !== undefined && typeof content.template === 'string' && keys.length === 1
+    ? undefined
+    : '`change.content` for a prompt block is { template } (the parameters carry over)';
 }
 
-// -------------------- request parsing --------------------
-
-type Parsed<T> =
-  | { readonly kind: 'ok'; readonly value: T }
-  | { readonly kind: 'err'; readonly message: string };
-
-interface DraftPayload {
-  readonly agentId: AgentId;
-  readonly agentVersion: string;
-  readonly tier: ProposedChange['tier'];
-  readonly change: ProposedChange['change'];
-  readonly patternRefs: readonly PatternRef[];
-  readonly hypothesis: string;
-  readonly proposerRuleId: string;
+function parseEvidence(raw: unknown): { judgmentIds?: string[] } | string {
+  if (raw === undefined) return {};
+  const evidence = obj(raw);
+  const ids = evidence?.judgmentIds;
+  const valid =
+    evidence !== undefined &&
+    Object.keys(evidence).every((k) => k === 'judgmentIds') &&
+    (ids === undefined || (Array.isArray(ids) && ids.every((id) => nonEmpty(id))));
+  if (!valid) return '`evidence` is { judgmentIds?: string[] }';
+  return ids === undefined ? {} : { judgmentIds: ids as string[] };
 }
 
-function parseDraftBody(body: unknown): Parsed<DraftPayload> {
-  if (body === null || typeof body !== 'object') {
-    return { kind: 'err', message: 'Request body must be an object' };
-  }
-  const b = body as Record<string, unknown>;
-  const agentId = b.agentId;
-  if (typeof agentId !== 'string' || agentId.length === 0) {
-    return { kind: 'err', message: 'Field `agentId` must be a non-empty string' };
-  }
-  const agentVersion = b.agentVersion;
-  if (typeof agentVersion !== 'string' || agentVersion.length === 0) {
-    return { kind: 'err', message: 'Field `agentVersion` must be a non-empty string' };
-  }
-  const tier = b.tier;
-  if (typeof tier !== 'string' || !PROPOSAL_TIERS.has(tier as ProposedChange['tier'])) {
-    return {
-      kind: 'err',
-      message: 'Field `tier` must be one of "prompt", "retrieval", "tool-config"',
-    };
-  }
-  const change = b.change;
-  if (change === null || typeof change !== 'object') {
-    return { kind: 'err', message: 'Field `change` must be an object' };
+function parseCreateBody(b: Record<string, unknown>): CreateBody | string {
+  if (!nonEmpty(b.agentId)) return '`agentId` is required';
+  if (!nonEmpty(b.fromVersion)) {
+    return '`fromVersion` is required: the agent version the change applies to';
   }
-  const patternRefs = b.patternRefs;
-  if (!Array.isArray(patternRefs)) {
-    return { kind: 'err', message: 'Field `patternRefs` must be an array' };
-  }
-  const hypothesis = b.hypothesis;
-  if (typeof hypothesis !== 'string' || hypothesis.length === 0) {
-    return { kind: 'err', message: 'Field `hypothesis` must be a non-empty string' };
-  }
-  const proposerRuleId = b.proposerRuleId;
-  if (typeof proposerRuleId !== 'string' || proposerRuleId.length === 0) {
-    return { kind: 'err', message: 'Field `proposerRuleId` must be a non-empty string' };
+  const scope = parseLiveScopeBody(b.scope);
+  if (scope.kind === 'err') return scope.message;
+  if (!TIERS.includes(b.tier as ProposalTier)) return `\`tier\` must be one of ${TIERS.join(', ')}`;
+  const tier = b.tier as ProposalTier;
+  const change = obj(b.change);
+  if (change === undefined) return '`change` must be an object: { blockId, content }';
+  if (!nonEmpty(change.blockId)) return '`change.blockId` is required';
+  const contentProblem = parseContent(tier, change.content);
+  if (contentProblem !== undefined) return contentProblem;
+  if (!nonEmpty(b.hypothesis)) {
+    return '`hypothesis` is required: what the change should improve, and why';
   }
+  const evidence = parseEvidence(b.evidence);
+  if (typeof evidence === 'string') return evidence;
   return {
-    kind: 'ok',
-    value: {
-      agentId: agentId as AgentId,
-      agentVersion,
-      tier: tier as ProposedChange['tier'],
-      change: change as ProposedChange['change'],
-      patternRefs: patternRefs as readonly PatternRef[],
-      hypothesis,
-      proposerRuleId,
-    },
+    agentId: b.agentId,
+    fromVersion: b.fromVersion,
+    scope: scope.scope,
+    tier,
+    blockId: change.blockId,
+    content: change.content as ProposedChange['change']['content'],
+    hypothesis: b.hypothesis,
+    ...evidence,
   };
 }
 
-interface DryRunPayload {
-  readonly datasetId: string;
-  readonly datasetVersion: string;
-  readonly criterion: PassCriterion;
+interface EvaluateBody {
+  readonly suiteId: string;
+  readonly objective: ProposalObjective;
+  readonly comparison?: EvalComparison;
 }
 
-function parseDryRunBody(body: unknown): Parsed<DryRunPayload> {
-  if (body === null || typeof body !== 'object') {
-    return { kind: 'err', message: 'Request body must be an object' };
-  }
-  const b = body as Record<string, unknown>;
-  const datasetId = b.datasetId;
-  if (typeof datasetId !== 'string' || datasetId.length === 0) {
-    return { kind: 'err', message: 'Field `datasetId` must be a non-empty string' };
+function parseEvaluateBody(b: Record<string, unknown>): EvaluateBody | string {
+  if (!nonEmpty(b.suiteId)) {
+    return '`suiteId` is required: the test set (a judged eval suite) to compare on';
   }
-  const datasetVersion = b.datasetVersion;
-  if (typeof datasetVersion !== 'string' || datasetVersion.length === 0) {
-    return { kind: 'err', message: 'Field `datasetVersion` must be a non-empty string' };
+  if (b.objective !== undefined && !OBJECTIVES.includes(b.objective as ProposalObjective)) {
+    return `\`objective\` must be one of ${OBJECTIVES.join(', ')}`;
   }
-  const rawCriterion = b.criterion;
-  if (rawCriterion === null || typeof rawCriterion !== 'object') {
-    return { kind: 'err', message: 'Field `criterion` must be an object' };
-  }
-  const cr = rawCriterion as Record<string, unknown>;
-  if (cr.kind === 'min-pass-rate') {
-    const minPassRate = cr.minPassRate;
-    if (typeof minPassRate !== 'number' || !Number.isFinite(minPassRate)) {
-      return {
-        kind: 'err',
-        message: 'Field `criterion.minPassRate` must be a finite number for kind "min-pass-rate"',
-      };
-    }
-    return {
-      kind: 'ok',
-      value: { datasetId, datasetVersion, criterion: { kind: 'min-pass-rate', minPassRate } },
-    };
-  }
-  if (cr.kind === 'strict-improvement') {
-    const baseline = cr.baselinePassRate;
-    const minDelta = cr.minDelta;
-    if (typeof baseline !== 'number' || !Number.isFinite(baseline)) {
-      return {
-        kind: 'err',
-        message:
-          'Field `criterion.baselinePassRate` must be a finite number for kind "strict-improvement"',
-      };
-    }
-    if (typeof minDelta !== 'number' || !Number.isFinite(minDelta)) {
-      return {
-        kind: 'err',
-        message: 'Field `criterion.minDelta` must be a finite number for kind "strict-improvement"',
-      };
-    }
-    return {
-      kind: 'ok',
-      value: {
-        datasetId,
-        datasetVersion,
-        criterion: { kind: 'strict-improvement', baselinePassRate: baseline, minDelta },
-      },
-    };
+  const extra = Object.keys(b).filter(
+    (k) =>
+      !['suiteId', 'objective', 'reads', 'repetitions', 'k', 'classWeights', 'sample'].includes(k),
+  );
+  if (extra.length > 0) {
+    return `\`${extra[0]}\` isn't a field of an evaluation: { suiteId, objective?, reads?, repetitions?, k?, classWeights?, sample? }`;
   }
+  const comparison = parseComparison(b);
+  if (comparison.kind === 'err') return comparison.message;
   return {
-    kind: 'err',
-    message: 'Field `criterion.kind` must be "min-pass-rate" or "strict-improvement"',
+    suiteId: b.suiteId,
+    objective: (b.objective as ProposalObjective | undefined) ?? 'weightedYesShare',
+    ...(comparison.value !== undefined && { comparison: comparison.value }),
   };
 }
 
-interface SubmitReviewPayload {
-  readonly requiredRole?: 'standard' | 'senior' | 'admin';
-  readonly expiresAt?: Timestamp;
-}
-
-function parseSubmitReviewBody(body: unknown): Parsed<SubmitReviewPayload> {
-  if (body === null || typeof body !== 'object') {
-    return { kind: 'err', message: 'Request body must be an object' };
-  }
-  const b = body as Record<string, unknown>;
-  const out: {
-    requiredRole?: 'standard' | 'senior' | 'admin';
-    expiresAt?: Timestamp;
-  } = {};
-  const requiredRole = b.requiredRole;
-  if (requiredRole !== undefined) {
-    if (
-      typeof requiredRole !== 'string' ||
-      !REVIEWER_ROLES.has(requiredRole as 'standard' | 'senior' | 'admin')
-    ) {
-      return {
+function optionalText(
+  body: Record<string, unknown>,
+  field: string,
+): { kind: 'ok'; value?: string } | { kind: 'err'; message: string } {
+  const v = body[field];
+  if (v === undefined) return { kind: 'ok' };
+  return nonEmpty(v)
+    ? { kind: 'ok', value: v }
+    : {
         kind: 'err',
-        message: 'Field `requiredRole` must be one of "standard", "senior", "admin"',
+        message: `\`${field}\` must be a non-empty string (at most ${MAX_TEXT} characters)`,
       };
-    }
-    out.requiredRole = requiredRole as 'standard' | 'senior' | 'admin';
-  }
-  const expiresAt = b.expiresAt;
-  if (expiresAt !== undefined) {
-    if (typeof expiresAt !== 'string' || Number.isNaN(new Date(expiresAt).getTime())) {
-      return { kind: 'err', message: 'Field `expiresAt` must be an ISO date string' };
-    }
-    out.expiresAt = expiresAt as Timestamp;
-  }
-  return { kind: 'ok', value: out };
 }
 
-interface ApplyPayload {
-  readonly newVersion?: string;
+/** The body as an object; `{}` when empty, `undefined` when it isn't a JSON object. */
+async function readBody(c: Ctx): Promise<Record<string, unknown> | undefined> {
+  const text = await c.req.text();
+  if (text.trim() === '') return {};
+  try {
+    return obj(JSON.parse(text));
+  } catch {
+    return undefined;
+  }
 }
 
-function parseApplyBody(body: unknown): Parsed<ApplyPayload> {
-  if (body === null || typeof body !== 'object') {
-    return { kind: 'err', message: 'Request body must be an object' };
-  }
-  const b = body as Record<string, unknown>;
-  const newVersion = b.newVersion;
-  if (newVersion !== undefined) {
-    if (typeof newVersion !== 'string' || newVersion.length === 0) {
-      return {
-        kind: 'err',
-        message: 'Field `newVersion` must be a non-empty string when present',
-      };
-    }
-    return { kind: 'ok', value: { newVersion } };
-  }
-  return { kind: 'ok', value: {} };
+// ---------- helpers ----------
+
+function fail(
+  c: Ctx,
+  code: string,
+  error: { code: string; message: string } & Record<string, unknown>,
+) {
+  c.status(statusFor(code) as never);
+  return c.json(toWireError(error, c.get('requestId')));
 }
 
-interface ReasonPayload {
-  readonly reason: string;
+function badInput(c: Ctx, message: string) {
+  return fail(c, 'bad-input', { code: 'bad-input', message });
 }
 
-function parseReasonBody(body: unknown): Parsed<ReasonPayload> {
-  if (body === null || typeof body !== 'object') {
-    return { kind: 'err', message: 'Request body must be an object' };
-  }
-  const b = body as Record<string, unknown>;
-  const reason = b.reason;
-  if (typeof reason !== 'string' || reason.length === 0) {
-    return { kind: 'err', message: 'Field `reason` must be a non-empty string' };
-  }
-  return { kind: 'ok', value: { reason } };
+function failWith(c: Ctx, error: ProposalServiceError) {
+  return fail(c, error.code, error);
 }