@kindgi/api 0.1.4 → 0.1.5

package/dist/person-grants-binding.d.ts

@@ -0,0 +1,77 @@
+import type { ReviewerRole } from '@kindgi/authz';
+import type { ProjectRole, TeamRole } from '@kindgi/platform';
+import type { Result, TenantId } from '@kindgi/types';
+/**
+ * A person's grants: what a person of the tenant may do, read in one
+ * call, and tenant admin given or taken (`/v1/identity/users/:id/grants`,
+ * `/grant`, `/ungrant`).
+ *
+ * The read lists what was granted *directly*: tenant admin, a role on a
+ * project (its memberships), a role in a team, and the reviewer roster.
+ * What a team's or an org's grants imply is not expanded. Project and
+ * team roles keep their own membership routes; only tenant admin is
+ * granted here, written before the call answers so the person's next
+ * request already holds it.
+ */
+export interface PersonGrants {
+    readonly userId: string;
+    /** Absent when the runtime has no authorization store: nothing grants it then. */
+    readonly tenantAdmin?: boolean;
+    /**
+     * A tenant member: reads the tenant's settings, not its projects. A
+     * person is one from being added. Absent when the runtime has no
+     * authorization store, or doesn't report it.
+     */
+    readonly tenantMember?: boolean;
+    /** Direct project memberships. */
+    readonly projects: readonly {
+        readonly projectId: string;
+        readonly role: ProjectRole;
+    }[];
+    /** Team memberships. */
+    readonly teams: readonly {
+        readonly teamId: string;
+        readonly role: TeamRole;
+    }[];
+    /** The person's active entry on the reviewer roster. */
+    readonly reviewer?: {
+        readonly role: ReviewerRole;
+    };
+}
+/** What `grant` and `ungrant` take: tenant admin (project and team roles have membership routes). */
+export type PersonGrant = {
+    readonly kind: 'tenant-admin';
+};
+export interface PersonRef {
+    readonly tenantId: TenantId;
+    readonly userId: string;
+}
+/** A change to a person's grants, and who made it: `user:<id>` or `service_account:<id>`. */
+export interface PersonGrantChange extends PersonRef {
+    readonly grant: PersonGrant;
+    readonly by?: string;
+}
+export type PersonGrantErrorCode = 
+/** No such person in the tenant's directory. */
+'identity-user-not-found'
+/** Granting to a person who was removed from the tenant. */
+ | 'identity-user-unregistered'
+/** Removing tenant admin from the only person who holds it. */
+ | 'last-tenant-admin'
+/** Removing tenant admin from the seed user, whom the runtime grants it at every boot. */
+ | 'seed-user-admin'
+/** The runtime has no authorization store to write grants to. */
+ | 'person-grants-unsupported';
+export interface PersonGrantError {
+    readonly code: PersonGrantErrorCode;
+    readonly message: string;
+}
+export interface PersonGrantsBinding {
+    /** The person's grants, or `null` when there's no such person. */
+    read(input: PersonRef): Promise<PersonGrants | null>;
+    /** Grant (a no-op when held); answers with the grants after. */
+    grant(input: PersonGrantChange): Promise<Result<PersonGrants, PersonGrantError>>;
+    /** Remove (a no-op when not held); answers with the grants after. */
+    ungrant(input: PersonGrantChange): Promise<Result<PersonGrants, PersonGrantError>>;
+}
+//# sourceMappingURL=person-grants-binding.d.ts.map

package/dist/person-grants-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"person-grants-binding.d.ts","sourceRoot":"","sources":["../src/person-grants-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IACzF,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,EAAE,CAAC;IAChF,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;KAAE,CAAC;CACrD;AAED,qGAAqG;AACrG,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6FAA6F;AAC7F,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,oBAAoB;AAC9B,gDAAgD;AAC9C,yBAAyB;AAC3B,4DAA4D;GAC1D,4BAA4B;AAC9B,+DAA+D;GAC7D,mBAAmB;AACrB,0FAA0F;GACxF,iBAAiB;AACnB,iEAAiE;GAC/D,2BAA2B,CAAC;AAEhC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACrD,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACjF,qEAAqE;IACrE,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC;CACpF"}

package/dist/person-grants-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=person-grants-binding.js.map

package/dist/person-grants-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"person-grants-binding.js","sourceRoot":"","sources":["../src/person-grants-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/proposal-service.d.ts

@@ -0,0 +1,121 @@
+import type { ProjectBinding } from '@kindgi/platform';
+import type { LiveScope, TenantId } from '@kindgi/types';
+import type { AgentRegistryBinding } from './agent-binding.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+import type { EvalComparison, EvalRunBinding } from './eval-run-binding.js';
+import type { GateApproval } from './gate.js';
+import type { AgentReleaseBindings, Promotion, PromotionActor } from './live-version-binding.js';
+import { type FixProposalStatus, type ProposalEvaluationOutcome } from './proposal-status.js';
+import { type PromotionRequestOutcome } from './routes/agent-releases.js';
+import type { ProposalDrafter, ProposalEvidence, ProposalObjective, ProposalTier, ProposedChange, StoredProposal, SupervisorBinding } from './supervisor-binding.js';
+/**
+ * The improvement-proposal lifecycle, from the bindings it runs on: what
+ * `/v1/proposals` serves, and what a runtime's improvement pass drafts
+ * and evaluates its proposal with. No authorization here: the route
+ * checks the caller; a pass acts as the runtime. Each call answers an
+ * outcome; an error carries the wire code the route answers with.
+ */
+export interface ProposalServiceDeps {
+    readonly store: Pick<SupervisorBinding, 'listProposals' | 'getProposal' | 'createProposal' | 'recordProposal'>;
+    readonly agents: AgentRegistryBinding;
+    readonly blocks: BlockRegistryBinding;
+    readonly evalRuns: EvalRunBinding;
+    readonly releases: AgentReleaseBindings;
+    readonly projects?: ProjectBinding;
+}
+/** An error with the code the API answers it with (`statusFor`), and its details. */
+export type ProposalServiceError = {
+    readonly code: string;
+    readonly message: string;
+} & Readonly<Record<string, unknown>>;
+export type ProposalOutcome<T> = {
+    readonly kind: 'ok';
+    readonly value: T;
+} | {
+    readonly kind: 'err';
+    readonly error: ProposalServiceError;
+};
+/** What a proposal's ids resolve to now, and the status that follows. */
+export interface ProposalFacts {
+    readonly status: FixProposalStatus;
+    readonly evaluation?: ProposalEvaluationOutcome | null;
+    readonly promotion?: Promotion | null;
+    /** For a promoted proposal: whether its version still serves the scope. */
+    readonly liveNow?: boolean;
+}
+export interface DraftProposalInput {
+    readonly tenantId: TenantId;
+    readonly agentId: string;
+    readonly fromVersion: string;
+    readonly scope: LiveScope;
+    readonly tier: ProposalTier;
+    readonly blockId: string;
+    readonly content: ProposedChange['change']['content'];
+    readonly hypothesis: string;
+    readonly evidence?: ProposalEvidence;
+    readonly drafter: ProposalDrafter;
+}
+export interface EvaluateProposalInput {
+    readonly tenantId: TenantId;
+    readonly proposal: StoredProposal;
+    readonly suiteId: string;
+    readonly objective: ProposalObjective;
+    readonly comparison?: EvalComparison;
+    /** Who it's done for: what the derived version records as `by`. */
+    readonly actor: PromotionActor;
+}
+/**
+ * What a promotion that a drafter (not a person) asks for needs even when
+ * the scope's policy asks for none: a reviewer (K2). Any reviewer may
+ * approve: the drafter, not a person, requested it.
+ */
+export declare const DRAFTED_PROPOSAL_APPROVAL: GateApproval;
+export declare function createProposalService(deps: ProposalServiceDeps): {
+    facts: (tenantId: TenantId) => (p: StoredProposal) => Promise<ProposalFacts>;
+    /**
+     * Store a proposal: new content for a block `fromVersion` pins, checked
+     * as publishing that block version would be. `deduped` when the same
+     * change from the same version for the same scope is open already.
+     */
+    draft(input: DraftProposalInput): Promise<ProposalOutcome<{
+        proposal: StoredProposal;
+        deduped: boolean;
+    }>>;
+    /**
+     * Publish the proposal's block version and derive its agent version
+     * (once: an evaluation again reuses them), then start the comparison.
+     * Needs a writable agent registry and a tenant-wide live version.
+     */
+    evaluate(input: EvaluateProposalInput): Promise<ProposalOutcome<StoredProposal>>;
+    /**
+     * A gated promotion of the candidate for the proposal's scope, with its
+     * evaluation's comparison. A drafter's proposal always waits for a
+     * reviewer (K2). `promotion` is the request's outcome, as promotions
+     * answer it; the proposal records its promotion once one is recorded.
+     */
+    request(input: {
+        readonly tenantId: TenantId;
+        readonly proposal: StoredProposal;
+        readonly actor: PromotionActor;
+        readonly reason?: string;
+    }): Promise<ProposalOutcome<{
+        proposal: StoredProposal;
+        promotion: PromotionRequestOutcome;
+    }>>;
+    /** The scope back on its own pin before the proposal's promotion (or unpinned). */
+    rollback(input: {
+        readonly tenantId: TenantId;
+        readonly proposal: StoredProposal;
+        readonly actor: PromotionActor;
+        readonly reason?: string;
+    }): Promise<ProposalOutcome<StoredProposal>>;
+    withdraw(input: {
+        readonly tenantId: TenantId;
+        readonly proposal: StoredProposal;
+        readonly actor: PromotionActor;
+        readonly reason: string;
+    }): Promise<ProposalOutcome<StoredProposal>>;
+};
+export type ProposalService = ReturnType<typeof createProposalService>;
+export declare function proposalNotFound(proposalId: string): ProposalServiceError;
+//# sourceMappingURL=proposal-service.d.ts.map

package/dist/proposal-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-service.d.ts","sourceRoot":"","sources":["../src/proposal-service.ts"],"names":[],"mappings":"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"}

package/dist/proposal-service.js

@@ -0,0 +1,447 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { createHash } from 'node:crypto';
+import { tuplesForCreate } from '@kindgi/authz';
+import { canonicalize } from '@kindgi/schema';
+import { blockEditDefinition, publishBlockEdit } from './block-publish.js';
+import { deriveAgentVersion } from './derive-agent-version.js';
+import { PROPOSAL_ACTIONS, evaluationOutcome, proposalActionAllowed, proposalStatus, } from './proposal-status.js';
+import { requestPromotion } from './routes/agent-releases.js';
+import { liveScopeToWire } from './routes/live-scope-wire.js';
+/**
+ * What a promotion that a drafter (not a person) asks for needs even when
+ * the scope's policy asks for none: a reviewer (K2). Any reviewer may
+ * approve: the drafter, not a person, requested it.
+ */
+export const DRAFTED_PROPOSAL_APPROVAL = {
+    role: 'standard',
+    count: 1,
+    separateApprover: false,
+};
+export function createProposalService(deps) {
+    const err = (error) => ({ kind: 'err', error });
+    /** A reader of proposal facts for one call: each agent's pins are read once. */
+    function facts(tenantId) {
+        const pins = new Map();
+        const pinsOf = (agentId) => {
+            const known = pins.get(agentId);
+            if (known !== undefined)
+                return known;
+            const found = deps.releases.live.list({ tenantId, agentId });
+            pins.set(agentId, found);
+            return found;
+        };
+        return async (p) => {
+            const promotion = p.promotionId === undefined
+                ? undefined
+                : await deps.releases.promotions.get(tenantId, p.promotionId);
+            let evaluation;
+            if (p.evaluation !== undefined) {
+                const run = await deps.evalRuns.get({ tenantId, runId: p.evaluation.evalRunId });
+                evaluation = run === null ? null : evaluationOutcome(p.evaluation.objective, run);
+            }
+            const status = proposalStatus(p, promotion, evaluation);
+            let liveNow;
+            if (status === 'promoted' && promotion !== undefined && promotion !== null) {
+                const all = await pinsOf(p.agentId);
+                liveNow = all.some((pin) => pin.promotionId === promotion.id);
+            }
+            return {
+                status,
+                ...(evaluation !== undefined && { evaluation }),
+                ...(promotion !== undefined && { promotion }),
+                ...(liveNow !== undefined && { liveNow }),
+            };
+        };
+    }
+    /** The 409 when the proposal's status doesn't allow `action`. */
+    async function refuseStatus(action, proposal, seen) {
+        const f = seen ?? (await facts(proposal.tenantId)(proposal));
+        if (proposalActionAllowed(action, f.status))
+            return undefined;
+        return invalidTransition(proposal, f.status, `it's ${f.status}, and ${action} needs one of: ${PROPOSAL_ACTIONS[action].join(', ')}.`);
+    }
+    /** Record a step; the 409 when another call recorded one first. */
+    async function record(proposal, step) {
+        const outcome = await deps.store.recordProposal({
+            tenantId: proposal.tenantId,
+            proposalId: proposal.id,
+            expectRevision: proposal.revision,
+            step,
+        });
+        if (outcome.kind === 'ok')
+            return { kind: 'ok', value: outcome.proposal };
+        if (outcome.kind === 'not-found')
+            return err(proposalNotFound(proposal.id));
+        return err({
+            code: 'proposal-invalid-state-transition',
+            message: `Proposal ${proposal.id} changed while this ran: read it again`,
+            proposalId: proposal.id,
+        });
+    }
+    /** Publish the block version and derive the agent version a proposal is evaluated as. */
+    async function makeCandidate(proposal, actor) {
+        const { tenantId } = proposal;
+        const { blockId, fromVersion } = proposal.change;
+        const from = await deps.blocks.getVersion({ tenantId, blockId, version: fromVersion });
+        if (from === null) {
+            return err(validationFailed(`Block "${blockId}" version ${fromVersion} is gone`, []));
+        }
+        const published = await publishBlockEdit({
+            blocks: deps.blocks,
+            tenantId,
+            from,
+            edit: editOf(proposal.tier, proposal.change.content),
+        });
+        if (published.kind === 'invalid') {
+            return err(validationFailed(`The proposal's content can't be published as block "${blockId}"`, published.issues));
+        }
+        const pinKind = proposal.tier === 'settings-block' ? 'settings' : 'prompts';
+        const userId = actor.kind === 'user' ? actor.id : undefined;
+        const derived = await deriveAgentVersion({
+            agents: deps.agents,
+            blocks: deps.blocks,
+            tenantId,
+            agentId: proposal.agentId,
+            from: proposal.fromVersion,
+            swaps: { [pinKind]: { [blockId]: published.version } },
+            label: `proposal ${proposal.id}`,
+            by: `${actor.kind}:${actor.id}`,
+            proposalId: proposal.id,
+            tuplesFor: (projectId) => (id) => tuplesForCreate({ kind: 'agent', id: id, tenantId, projectId }, userId ?? '00000000-0000-0000-0000-000000000000'),
+        });
+        if (derived.kind !== 'ok' && derived.kind !== 'reused') {
+            return err(validationFailed(derived.kind === 'invalid'
+                ? `Can't derive a version from ${proposal.fromVersion}`
+                : `Can't derive a version from ${proposal.fromVersion} (${derived.kind})`, derived.kind === 'invalid' ? derived.issues : []));
+        }
+        const { agent } = derived;
+        if (agent.pinsDigest === undefined)
+            throw new Error('a derived version is pinned');
+        return {
+            kind: 'ok',
+            value: {
+                agentVersion: agent.version,
+                blockVersion: published.version,
+                pinsDigest: agent.pinsDigest,
+            },
+        };
+    }
+    return {
+        facts,
+        /**
+         * Store a proposal: new content for a block `fromVersion` pins, checked
+         * as publishing that block version would be. `deduped` when the same
+         * change from the same version for the same scope is open already.
+         */
+        async draft(input) {
+            const { tenantId } = input;
+            const from = await deps.agents.getVersion({
+                tenantId,
+                agentId: input.agentId,
+                version: input.fromVersion,
+            });
+            if (from === null || from.unregisteredAt !== undefined) {
+                return err({
+                    code: 'agent-version-not-found',
+                    message: `${input.agentId} has no active version ${input.fromVersion}`,
+                });
+            }
+            const pinned = await pinnedBlock(deps.blocks, tenantId, from, input.tier, input.blockId);
+            if (pinned.kind === 'invalid')
+                return err(validationFailed(pinned.message, pinned.issues));
+            const edit = editOf(input.tier, input.content);
+            const checked = await blockEditDefinition({ blocks: deps.blocks, tenantId, from: pinned.block, edit }, pinned.block.version);
+            if (checked.kind === 'invalid') {
+                return err(validationFailed(`The new content isn't a valid version of block "${input.blockId}"`, checked.issues));
+            }
+            if (sameContent(pinned.block, edit)) {
+                return err(validationFailed(`The proposal doesn't change block "${input.blockId}"`, [
+                    {
+                        path: '/change/content',
+                        message: `equals version ${pinned.block.version}, which ${input.fromVersion} pins`,
+                    },
+                ]));
+            }
+            const change = {
+                blockId: input.blockId,
+                fromVersion: pinned.block.version,
+                content: input.content,
+            };
+            const outcome = await deps.store.createProposal({
+                tenantId,
+                ...(from.projectId !== undefined && { projectId: from.projectId }),
+                agentId: input.agentId,
+                fromVersion: input.fromVersion,
+                scope: input.scope,
+                tier: input.tier,
+                change,
+                hypothesis: input.hypothesis,
+                ...(input.evidence !== undefined && { evidence: input.evidence }),
+                drafter: input.drafter,
+                fingerprint: fingerprintOf(input, change),
+            });
+            return {
+                kind: 'ok',
+                value: { proposal: outcome.proposal, deduped: outcome.kind === 'dedup' },
+            };
+        },
+        /**
+         * Publish the proposal's block version and derive its agent version
+         * (once: an evaluation again reuses them), then start the comparison.
+         * Needs a writable agent registry and a tenant-wide live version.
+         */
+        async evaluate(input) {
+            const { tenantId } = input;
+            let proposal = input.proposal;
+            const agentId = proposal.agentId;
+            const refused = await refuseStatus('evaluate', proposal);
+            if (refused !== undefined)
+                return err(refused);
+            // Evaluating derives an agent version: not into a registry that takes no writes.
+            if (deps.agents.readOnly !== undefined) {
+                return err({ code: 'registry-read-only', message: deps.agents.readOnly.reason });
+            }
+            // A version promoted nowhere is still the agent's latest, and the
+            // latest serves every scope nothing is pinned for.
+            if ((await deps.releases.live.resolve({ tenantId, agentId })) === null) {
+                return err({
+                    code: 'proposal-needs-pin',
+                    message: `${agentId} has no live version for the whole tenant, so a new version of it would serve every scope nothing is pinned for. Promote its current version for the tenant first (scope { "kind": "tenant" }), then evaluate.`,
+                });
+            }
+            if (proposal.candidate === undefined) {
+                const made = await makeCandidate(proposal, input.actor);
+                if (made.kind === 'err')
+                    return made;
+                const recorded = await record(proposal, { kind: 'candidate', candidate: made.value });
+                if (recorded.kind === 'err')
+                    return recorded;
+                proposal = recorded.value;
+            }
+            const candidate = proposal.candidate;
+            if (candidate === undefined)
+                throw new Error('a recorded candidate is on the proposal');
+            const version = await deps.agents.getVersion({
+                tenantId,
+                agentId: proposal.agentId,
+                version: candidate.agentVersion,
+            });
+            if (version === null ||
+                version.unregisteredAt !== undefined ||
+                version.projectId === undefined) {
+                return err({
+                    code: 'agent-version-not-found',
+                    message: `The candidate ${agentId} ${candidate.agentVersion} is unregistered: withdraw this proposal and draft it again`,
+                });
+            }
+            const started = await deps.evalRuns.start({
+                tenantId,
+                projectId: version.projectId,
+                suiteId: input.suiteId,
+                agentRef: { agentId: proposal.agentId, version: candidate.agentVersion },
+                correlationId: `proposal:${proposal.id}`,
+                ...(input.comparison !== undefined && { comparison: input.comparison }),
+            });
+            if (started.kind !== 'ok')
+                return err(startError(started));
+            return record(proposal, {
+                kind: 'evaluation',
+                evaluation: {
+                    evalRunId: started.runId,
+                    suiteId: input.suiteId,
+                    objective: input.objective,
+                    startedAt: new Date().toISOString(),
+                },
+            });
+        },
+        /**
+         * A gated promotion of the candidate for the proposal's scope, with its
+         * evaluation's comparison. A drafter's proposal always waits for a
+         * reviewer (K2). `promotion` is the request's outcome, as promotions
+         * answer it; the proposal records its promotion once one is recorded.
+         */
+        async request(input) {
+            const { tenantId, proposal } = input;
+            const refused = await refuseStatus('request', proposal);
+            if (refused !== undefined)
+                return err(refused);
+            const { candidate, evaluation } = proposal;
+            if (candidate === undefined || evaluation === undefined) {
+                throw new Error('an evaluated proposal has a candidate and an evaluation');
+            }
+            const promotion = await requestPromotion(deps.agents, deps.releases, {
+                evalRuns: deps.evalRuns,
+                ...(deps.projects !== undefined && { projects: deps.projects }),
+            }, {
+                tenantId,
+                agentId: proposal.agentId,
+                version: candidate.agentVersion,
+                scope: proposal.scope,
+                requestedBy: input.actor,
+                reason: input.reason ?? `Improvement proposal ${proposal.id}`,
+                evalRunId: evaluation.evalRunId,
+            }, proposal.drafter.kind === 'person' ? {} : { requireApproval: DRAFTED_PROPOSAL_APPROVAL });
+            if (promotion.kind !== 'ok')
+                return { kind: 'ok', value: { proposal, promotion } };
+            const recorded = await record(proposal, {
+                kind: 'promotion',
+                promotionId: promotion.promotion.id,
+            });
+            if (recorded.kind === 'err')
+                return recorded;
+            return { kind: 'ok', value: { proposal: recorded.value, promotion } };
+        },
+        /** The scope back on its own pin before the proposal's promotion (or unpinned). */
+        async rollback(input) {
+            const { tenantId, proposal } = input;
+            const seen = await facts(tenantId)(proposal);
+            const refused = await refuseStatus('rollback', proposal, seen);
+            if (refused !== undefined)
+                return err(refused);
+            const promotion = seen.promotion;
+            if (promotion === null || promotion === undefined || seen.liveNow !== true) {
+                return err(invalidTransition(proposal, seen.status, "its version doesn't serve the scope anymore (the scope was promoted, rolled back or unpinned since), so there's nothing of it to roll back."));
+            }
+            const request = {
+                tenantId,
+                agentId: proposal.agentId,
+                scope: proposal.scope,
+                requestedBy: input.actor,
+                reason: input.reason ?? `Rolled back improvement proposal ${proposal.id}`,
+            };
+            // Back to the scope's own pin before; with none, it falls back to the scope above.
+            const outcome = promotion.fromVersion === null
+                ? await deps.releases.promotions.unpin(request)
+                : await deps.releases.promotions.rollback({
+                    ...request,
+                    toVersion: promotion.fromVersion,
+                });
+            if (outcome.kind === 'err')
+                return err({ ...outcome.error });
+            return record(proposal, {
+                kind: 'rolled-back',
+                rolledBack: {
+                    at: new Date().toISOString(),
+                    promotionId: outcome.value.id,
+                    by: `${input.actor.kind}:${input.actor.id}`,
+                    ...(input.reason !== undefined && { reason: input.reason }),
+                },
+            });
+        },
+        async withdraw(input) {
+            const refused = await refuseStatus('withdraw', input.proposal);
+            if (refused !== undefined)
+                return err(refused);
+            return record(input.proposal, {
+                kind: 'withdrawn',
+                withdrawn: {
+                    at: new Date().toISOString(),
+                    by: `${input.actor.kind}:${input.actor.id}`,
+                    reason: input.reason,
+                },
+            });
+        },
+    };
+}
+// ---------- helpers ----------
+export function proposalNotFound(proposalId) {
+    return { code: 'proposal-not-found', message: `No proposal ${proposalId}`, proposalId };
+}
+function invalidTransition(proposal, status, why) {
+    return {
+        code: 'proposal-invalid-state-transition',
+        message: `Proposal ${proposal.id}: ${why}`,
+        proposalId: proposal.id,
+        status,
+    };
+}
+function validationFailed(message, issues) {
+    return {
+        code: 'validation-failed',
+        message,
+        issues: issues,
+    };
+}
+function startError(outcome) {
+    switch (outcome.kind) {
+        case 'suite-not-found':
+            return {
+                code: 'eval-suite-not-found',
+                message: `No eval suite registered with id "${outcome.suiteId}"`,
+                suiteId: outcome.suiteId,
+            };
+        case 'dispatcher-not-registered':
+            return {
+                code: 'dispatcher-not-registered',
+                message: `No eval-run dispatcher registered for kind "${outcome.evalKind}"`,
+            };
+        case 'dispatcher-input-invalid':
+            return { code: 'dispatcher-input-invalid', message: outcome.message };
+        case 'project-not-found':
+            return {
+                code: 'bad-input',
+                message: `The candidate's project "${outcome.projectId}" isn't in this tenant`,
+            };
+    }
+}
+function editOf(tier, content) {
+    return tier === 'settings-block'
+        ? { kind: 'settings', values: content.values }
+        : { kind: 'prompt', template: content.template };
+}
+function sameContent(pinned, edit) {
+    if (pinned.kind === 'settings' && edit.kind === 'settings') {
+        return canonicalize(pinned.content.values) === canonicalize(edit.values);
+    }
+    return pinned.kind === 'prompt' && edit.kind === 'prompt'
+        ? pinned.content.template === edit.template
+        : false;
+}
+/** The block version `from` pins for the tier, or why there's none to change. */
+async function pinnedBlock(blocks, tenantId, from, tier, blockId) {
+    const kind = tier === 'settings-block' ? 'settings' : 'prompts';
+    const what = tier === 'settings-block' ? 'settings' : 'prompt';
+    const named = `${from.id} ${from.version}`;
+    if (from.pins === undefined) {
+        return {
+            kind: 'invalid',
+            message: `${named} has no pins (it was published before pins); publish it again to pin it`,
+            issues: [],
+        };
+    }
+    const version = from.pins[kind][blockId];
+    if (version === undefined) {
+        return {
+            kind: 'invalid',
+            message: `${named} doesn't use ${what} block "${blockId}"`,
+            issues: [
+                {
+                    path: '/change/blockId',
+                    message: `not a ${what} block this version pins; adding a block is a code change`,
+                },
+            ],
+        };
+    }
+    const block = await blocks.getVersion({ tenantId, blockId, version });
+    if (block === null) {
+        return {
+            kind: 'invalid',
+            message: `Block "${blockId}" version ${version}, which ${named} pins, isn't in the block store`,
+            issues: [],
+        };
+    }
+    return { kind: 'ok', block };
+}
+/** The same change, from the same version, for the same scope, is one proposal. */
+function fingerprintOf(input, change) {
+    const canonical = canonicalize({
+        agentId: input.agentId,
+        fromVersion: input.fromVersion,
+        scope: liveScopeToWire(input.scope),
+        tier: input.tier,
+        change,
+    });
+    return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+//# sourceMappingURL=proposal-service.js.map