@kindgi/api 0.1.4 → 0.1.5

package/dist/routes/proposals.js

@@ -1,581 +1,414 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 import { Hono } from 'hono';
+import { ref } from '@kindgi/authz';
 import { statusFor, toWireError } from '../errors.js';
+import { createProposalService, proposalNotFound, } from '../proposal-service.js';
+import { FIX_PROPOSAL_STATUSES, } from '../proposal-status.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 = new Set([
-    'draft',
-    'dry-running',
-    'dry-run-passed',
-    'dry-run-failed',
-    'proposed-for-review',
-    'approved',
-    'rejected',
-    'applied',
-    'rolled-back',
-    'withdrawn',
-]);
-const PROPOSAL_TIERS = new Set([
-    'prompt',
-    'retrieval',
-    'tool-config',
-]);
-const REVIEWER_ROLES = new Set([
-    'standard',
-    'senior',
-    'admin',
-]);
+const TIERS = ['settings-block', 'prompt-block'];
+const OBJECTIVES = ['weightedYesShare', 'weightedPrecisionAtK'];
+const MAX_TEXT = 2000;
 /**
- * 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) {
+export function proposalsRouter(store, deps, authorizer, mount) {
     const r = new Hono();
-    // ---------- 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'));
-            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) ----------
+    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, action, agentId) {
+        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})`,
+        });
+    }
+    /** The proposal, if it exists and the caller may read it (else the 404). */
+    async function load(c) {
+        const proposalId = c.req.param('proposalId') ?? '';
+        const stored = await store.getProposal({
+            tenantId: c.get('tenantId'),
+            proposalId: proposalId,
+        });
+        const hidden = stored !== null &&
+            authorizer !== undefined &&
+            !(await authorizer.can(c, 'read', ref('agent', stored.agentId)));
+        if (stored === null || hidden)
+            return failWith(c, proposalNotFound(proposalId));
+        return stored;
+    }
+    async function answer(c, stored, status = 200) {
+        const f = await service.facts(c.get('tenantId'))(stored);
+        c.status(status);
+        return c.json(serialize(stored, f));
+    }
+    /** Read the body and the proposal, and check the caller may `action` it. */
+    async function prepare(c, action) {
+        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);
+        return denied ?? { body, proposal };
+    }
+    // ---------- GET / ----------
     r.get('/', async (c) => {
-        const requestId = c.get('requestId');
         const tenantId = c.get('tenantId');
-        const supervisorId = c.req.header('x-supervisor-id');
-        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;
-        if (statusRaw !== undefined && statusRaw.length > 0) {
-            if (!FIX_PROPOSAL_STATUSES.has(statusRaw)) {
-                c.status(statusFor('bad-input'));
-                return c.json(toWireError({ code: 'bad-input', message: `Unknown \`status\` value: ${statusRaw}` }, requestId));
-            }
-            status = statusRaw;
-        }
-        let tier;
-        if (tierRaw !== undefined && tierRaw.length > 0) {
-            if (!PROPOSAL_TIERS.has(tierRaw)) {
-                c.status(statusFor('bad-input'));
-                return c.json(toWireError({ code: 'bad-input', message: `Unknown \`tier\` value: ${tierRaw}` }, requestId));
-            }
-            tier = tierRaw;
-        }
-        const scopeParsed = parseScopeParams(c.req.query(), { tenantId });
-        if (scopeParsed.kind === 'err') {
-            c.status(statusFor('scope-invalid'));
-            return c.json(toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId));
-        }
-        const page = await binding.listProposals({
+        const status = c.req.query('status');
+        if (status !== undefined && !FIX_PROPOSAL_STATUSES.includes(status)) {
+            return badInput(c, `Unknown \`status\`: ${status}`);
+        }
+        const tier = c.req.query('tier');
+        if (tier !== undefined && !TIERS.includes(tier)) {
+            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 }),
-            ...(status !== undefined && { status }),
-            ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw }),
-            ...(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 }),
+            ...(agentId !== undefined && agentId !== '' && { agentId: agentId }),
+            ...(tier !== undefined && { tier: tier }),
+            ...(scope.scope !== undefined && { liveScope: scope.scope }),
         });
+        const readable = authorizer === undefined
+            ? page.data
+            : await authorizer.filterByCan(c, 'read', page.data, (p) => ref('agent', p.agentId));
+        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 }),
         });
     });
     // ---------- GET /:proposalId ----------
     r.get('/:proposalId', async (c) => {
-        const requestId = c.get('requestId');
-        const tenantId = c.get('tenantId');
-        const supervisorId = c.req.header('x-supervisor-id');
-        const proposalId = c.req.param('proposalId');
-        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');
-        const supervisorId = c.req.header('x-supervisor-id');
-        let body;
-        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'),
+            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');
-        const supervisorId = c.req.header('x-supervisor-id');
-        const proposalId = c.req.param('proposalId');
-        let body;
-        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');
-        const supervisorId = c.req.header('x-supervisor-id');
-        const proposalId = c.req.param('proposalId');
-        // Body is optional — every field on submit-review is an override.
-        let body = {};
-        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'));
-            return c.json(toWireError({
-                code: 'ground-layer-violation',
-                message: `Proposal ${outcome.proposalId} violated ground guardrail ${outcome.guardrailId}: ${outcome.reason}`,
-                proposalId: outcome.proposalId,
-                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,
-            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'),
+            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');
-        const supervisorId = c.req.header('x-supervisor-id');
-        const proposalId = c.req.param('proposalId');
-        let body = {};
-        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 }),
-        });
-        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,
-            appliedVersion: outcome.appliedVersion,
-            appliedAt: outcome.appliedAt,
+    // ---------- 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'),
+            proposal: ready.proposal,
+            actor: actorOf(c),
+            ...(reason.value !== undefined && { reason: reason.value }),
         });
+        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 });
+        }
+        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');
-        const supervisorId = c.req.header('x-supervisor-id');
-        const proposalId = c.req.param('proposalId');
-        let body;
-        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,
-            rolledBackAt: outcome.rolledBackAt,
+        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'),
+            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');
-        const supervisorId = c.req.header('x-supervisor-id');
-        const proposalId = c.req.param('proposalId');
-        let body;
-        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'),
+            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 --------------------
-function serializeProposal(p) {
+// ---------- wire ----------
+function evaluationWire(stored, seen) {
+    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, f) {
+    const promotion = f.promotion ?? undefined;
     return {
         id: p.id,
-        tenantId: p.tenantId,
-        supervisorId: p.supervisorId,
         agentId: p.agentId,
-        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,
+        ...(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 }),
-        ...(p.rolledBackAt !== undefined && { rolledBackAt: p.rolledBackAt }),
+        ...(p.rolledBack !== undefined && { rolledBack: p.rolledBack }),
+        ...(p.withdrawn !== undefined && { withdrawn: p.withdrawn }),
         createdAt: p.createdAt,
         updatedAt: p.updatedAt,
-        ...(p.resolvedAt !== undefined && { resolvedAt: p.resolvedAt }),
     };
 }
-function badInput(c, requestId, message) {
-    c.status(statusFor('bad-input'));
-    return c.json(toWireError({ code: 'bad-input', message }, requestId));
+function obj(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
 }
-function proposalNotFound(c, requestId, proposalId) {
-    c.status(statusFor('proposal-not-found'));
-    return c.json(toWireError({
-        code: 'proposal-not-found',
-        message: `No proposal with id "${proposalId}"`,
-        proposalId: proposalId,
-    }, requestId));
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() !== '' && value.length <= MAX_TEXT;
 }
-function invalidTransition(c, requestId, proposalId, from, to) {
-    c.status(statusFor('proposal-invalid-state-transition'));
-    return c.json(toWireError({
-        code: 'proposal-invalid-state-transition',
-        message: `Cannot transition proposal ${proposalId} from ${from} to ${to}`,
-        proposalId: proposalId,
-        from,
-        to,
-    }, requestId));
+function parseContent(tier, raw) {
+    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)';
 }
-function runtimeError(c, requestId, code, message) {
-    c.status(statusFor(code));
-    return c.json(toWireError({ code, message }, requestId));
+function parseEvidence(raw) {
+    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 };
 }
-function parseDraftBody(body) {
-    if (body === null || typeof body !== 'object') {
-        return { kind: 'err', message: 'Request body must be an object' };
-    }
-    const b = body;
-    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' };
+function parseCreateBody(b) {
+    if (!nonEmpty(b.agentId))
+        return '`agentId` is required';
+    if (!nonEmpty(b.fromVersion)) {
+        return '`fromVersion` is required: the agent version the change applies to';
     }
+    const scope = parseLiveScopeBody(b.scope);
+    if (scope.kind === 'err')
+        return scope.message;
+    if (!TIERS.includes(b.tier))
+        return `\`tier\` must be one of ${TIERS.join(', ')}`;
     const tier = b.tier;
-    if (typeof tier !== 'string' || !PROPOSAL_TIERS.has(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' };
-    }
-    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 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,
-            agentVersion,
-            tier: tier,
-            change: change,
-            patternRefs: patternRefs,
-            hypothesis,
-            proposerRuleId,
-        },
+        agentId: b.agentId,
+        fromVersion: b.fromVersion,
+        scope: scope.scope,
+        tier,
+        blockId: change.blockId,
+        content: change.content,
+        hypothesis: b.hypothesis,
+        ...evidence,
     };
 }
-function parseDryRunBody(body) {
-    if (body === null || typeof body !== 'object') {
-        return { kind: 'err', message: 'Request body must be an object' };
+function parseEvaluateBody(b) {
+    if (!nonEmpty(b.suiteId)) {
+        return '`suiteId` is required: the test set (a judged eval suite) to compare on';
     }
-    const b = body;
-    const datasetId = b.datasetId;
-    if (typeof datasetId !== 'string' || datasetId.length === 0) {
-        return { kind: 'err', message: 'Field `datasetId` must be a non-empty string' };
+    if (b.objective !== undefined && !OBJECTIVES.includes(b.objective)) {
+        return `\`objective\` must be one of ${OBJECTIVES.join(', ')}`;
     }
-    const datasetVersion = b.datasetVersion;
-    if (typeof datasetVersion !== 'string' || datasetVersion.length === 0) {
-        return { kind: 'err', message: 'Field `datasetVersion` must be a non-empty string' };
-    }
-    const rawCriterion = b.criterion;
-    if (rawCriterion === null || typeof rawCriterion !== 'object') {
-        return { kind: 'err', message: 'Field `criterion` must be an object' };
-    }
-    const cr = rawCriterion;
-    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 ?? 'weightedYesShare',
+        ...(comparison.value !== undefined && { comparison: comparison.value }),
     };
 }
-function parseSubmitReviewBody(body) {
-    if (body === null || typeof body !== 'object') {
-        return { kind: 'err', message: 'Request body must be an object' };
-    }
-    const b = body;
-    const out = {};
-    const requiredRole = b.requiredRole;
-    if (requiredRole !== undefined) {
-        if (typeof requiredRole !== 'string' ||
-            !REVIEWER_ROLES.has(requiredRole)) {
-            return {
-                kind: 'err',
-                message: 'Field `requiredRole` must be one of "standard", "senior", "admin"',
-            };
-        }
-        out.requiredRole = requiredRole;
-    }
-    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;
-    }
-    return { kind: 'ok', value: out };
+function optionalText(body, field) {
+    const v = body[field];
+    if (v === undefined)
+        return { kind: 'ok' };
+    return nonEmpty(v)
+        ? { kind: 'ok', value: v }
+        : {
+            kind: 'err',
+            message: `\`${field}\` must be a non-empty string (at most ${MAX_TEXT} characters)`,
+        };
 }
-function parseApplyBody(body) {
-    if (body === null || typeof body !== 'object') {
-        return { kind: 'err', message: 'Request body must be an object' };
+/** The body as an object; `{}` when empty, `undefined` when it isn't a JSON object. */
+async function readBody(c) {
+    const text = await c.req.text();
+    if (text.trim() === '')
+        return {};
+    try {
+        return obj(JSON.parse(text));
     }
-    const b = body;
-    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 } };
+    catch {
+        return undefined;
     }
-    return { kind: 'ok', value: {} };
 }
-function parseReasonBody(body) {
-    if (body === null || typeof body !== 'object') {
-        return { kind: 'err', message: 'Request body must be an object' };
-    }
-    const b = body;
-    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 } };
+// ---------- helpers ----------
+function fail(c, code, error) {
+    c.status(statusFor(code));
+    return c.json(toWireError(error, c.get('requestId')));
+}
+function badInput(c, message) {
+    return fail(c, 'bad-input', { code: 'bad-input', message });
+}
+function failWith(c, error) {
+    return fail(c, error.code, error);
 }
 //# sourceMappingURL=proposals.js.map