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

package/src/handler-binding.ts

@@ -2,7 +2,8 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
-import type { FlowId, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
+import type { FlowVersionOverrides } from '@kindgi/flow';
+import type { FlowId, ProjectId, RunId, ScopeSegment, Semver, TenantId } from '@kindgi/types';
 
 /**
  * Callback the platform HTTP surface hands off to when it receives
@@ -72,8 +73,18 @@ export interface InvokeAgentBindingInput {
    */
   readonly projectId?: ProjectId;
   readonly agentId: AgentId;
-  /** Omit → binding chooses the latest registered version. */
+  /**
+   * Omit → the binding chooses: the conversation's own version for a
+   * follow-up turn, else the version live for the run's scope, else the
+   * latest registered.
+   */
   readonly agentVersion?: Semver;
+  /**
+   * The run's segment path below its project, coarse to fine (an
+   * app-defined finer scope, e.g. company then role): a live version
+   * pinned on a prefix of it serves the run.
+   */
+  readonly segments?: readonly ScopeSegment[];
   /**
    * Opaque payload forwarded from the request body's `input` field.
    * The binding is responsible for coercing this into whatever shape
@@ -97,6 +108,8 @@ export interface InvokeFlowBindingInput {
   readonly projectId?: ProjectId;
   readonly flowId: FlowId;
   readonly flowVersion?: Semver;
+  /** The run's segment path, as for an agent run: its agent steps resolve live versions with it. */
+  readonly segments?: readonly ScopeSegment[];
   readonly input: unknown;
   readonly dryRun?: boolean;
   /**
@@ -107,6 +120,8 @@ export interface InvokeFlowBindingInput {
    * can't run in the background may treat `false` like `true`.
    */
   readonly wait?: boolean;
+  /** Agents and tools to run at other exact versions than the flow version's pins (`RunFlowInput.versions`). */
+  readonly versions?: FlowVersionOverrides;
 }
 
 export type RunHandlerOutcome =

package/src/index.ts

@@ -239,6 +239,7 @@ export type {
   AgentUnregisterInput,
   AgentUnregisterOutcome,
 } from './agent-binding.js';
+export type { RegistryReadOnly } from './registry-read-only.js';
 export type {
   FlowGetInput,
   FlowGetVersionInput,
@@ -330,7 +331,12 @@ export type {
   PolicyVersionPage,
   PolicyVersionRow,
 } from '@kindgi/policy-contract';
-export { JUDGE_CLASS_SCOPE_KINDS, VERDICTS, judgeClassApplies } from './judgment-binding.js';
+export {
+  JUDGE_CLASS_SCOPE_KINDS,
+  VERDICTS,
+  judgeClassApplies,
+  whyNotAssertable,
+} from './judgment-binding.js';
 export type {
   EvalCaseListInput,
   EvalCasePage,
@@ -343,6 +349,8 @@ export { MAX_JUDGED_CASES } from './routes/judged-suites.js';
 export { MAX_JUDGED_HISTORY } from './routes/judgment-context.js';
 export type {
   JudgeClass,
+  JudgeClassAssertableBy,
+  JudgeClassAsserter,
   JudgeClassCreateInput,
   JudgeClassCreateOutcome,
   JudgeClassGetInput,
@@ -385,6 +393,42 @@ export type {
   BlockReinstateOutcome,
   BlockVersionInput,
 } from './block-binding.js';
+export type {
+  AgentReleaseBindings,
+  ListPromotionsInput,
+  LivePin,
+  LiveResolution,
+  LiveResolveInput,
+  LiveVersionBinding,
+  PromoteInput,
+  Promotion,
+  PromotionAction,
+  PromotionActor,
+  PromotionBinding,
+  PromotionError,
+  PromotionErrorCode,
+  PromotionRequestInput,
+  PromotionStatus,
+  RollbackInput,
+  UnpinInput,
+} from './live-version-binding.js';
+export type {
+  GateMetricName,
+  GateMetricSpec,
+  GatePolicy,
+  GatePolicyBinding,
+  GatePolicyError,
+  GatePolicyErrorCode,
+  GatePolicyListInput,
+  GatePolicyPublishInput,
+  GatePolicyRef,
+  GatePolicySpec,
+  GatePolicyVersionInput,
+} from './gate-policy-binding.js';
+export { GATE_METRICS } from './gate-policy-binding.js';
+export type { GateApproval, GateCheck, GateInput, GateResult } from './gate.js';
+export { evaluateGate, gateApproval } from './gate.js';
+export type { AgentReleaseGateDeps } from './routes/agent-releases.js';
 export { EVAL_KINDS } from './eval-suite-binding.js';
 export type {
   EvalKind,
@@ -406,6 +450,7 @@ export { EVAL_RUN_STATUSES } from './eval-run-binding.js';
 export type {
   AgentRef,
   EvalBaseline,
+  EvalClassWeights,
   EvalComparison,
   EvalReads,
   EvalRun,
@@ -684,6 +729,7 @@ export type { JsonSchema } from './openapi/schemas.js';
 
 export type {
   RetentionBinding,
+  RetentionPolicyConflict,
   RetentionScheduledInput,
   RetentionScheduledItem,
   RetentionScheduledPage,

package/src/judged-dispatcher.ts

@@ -16,10 +16,12 @@
  */
 
 import type { ReplayTurnReport } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { RunId } from '@kindgi/types';
 
+import type { AgentRegistryBinding } from './agent-binding.js';
 import type { EvalCaseStoreBinding, JudgedEvalCase } from './eval-case-binding.js';
-import type { AgentRef, EvalComparison, FlowRef } from './eval-run-binding.js';
+import type { AgentRef, EvalClassWeights, EvalComparison, FlowRef } from './eval-run-binding.js';
 import type {
   DispatchContext,
   DispatchResult,
@@ -80,8 +82,24 @@ export type RecordedVersion =
 
 /** What ran on the cases: an agent version, or a flow version. */
 export type ComparisonCandidate =
-  | { readonly kind: 'agent'; readonly agentId: string; readonly version: string }
-  | { readonly kind: 'flow'; readonly flowId: string; readonly version: string };
+  | {
+      readonly kind: 'agent';
+      readonly agentId: string;
+      readonly version: string;
+      /**
+       * The version's `pinsDigest`: what it ran, as a promotion gate checks.
+       * Absent for a version published before pins, and from a dispatcher
+       * without an agent registry.
+       */
+      readonly pinsDigest?: string;
+    }
+  | {
+      readonly kind: 'flow';
+      readonly flowId: string;
+      readonly version: string;
+      /** Agents and tools its replays ran at other versions than the flow version's pins. */
+      readonly versions?: FlowVersionOverrides;
+    };
 
 /** What a comparison eval run concluded: what a promotion gate reads. */
 export interface JudgedComparisonSummary {
@@ -106,6 +124,12 @@ export interface JudgedComparisonSummary {
    */
   readonly stopped: number;
   readonly reads: EvalComparison['reads'];
+  /**
+   * Which judgments counted: `restricted-only` weighs a judgment not
+   * recorded under a restricted class 0 (a gate can require it). Absent
+   * from a summary recorded before T200: `as-recorded`.
+   */
+  readonly classWeights?: EvalClassWeights;
   /** The models that answered the candidate's replays, and how many replays each. */
   readonly sampling: {
     readonly models: readonly {
@@ -145,11 +169,16 @@ export interface JudgedCaseResult {
 
 export interface JudgedDispatcherOptions {
   readonly cases: EvalCaseStoreBinding;
+  /** Where the candidate's `pinsDigest` is read, for the summary. */
+  readonly agents?: Pick<AgentRegistryBinding, 'getVersion'>;
 }
 
 /** Cases read per page. */
 const CASE_PAGE = 100;
 
+export const VERSIONS_NEED_A_FLOW =
+  '`versions` runs a flow with some of its agents or tools at other versions: it needs `flowRef`.';
+
 function validateComparison(
   suite: { readonly spec: Readonly<Record<string, unknown>> },
   target: AgentRef | FlowRef,
@@ -168,6 +197,9 @@ function validateComparison(
     return { kind: 'err', message: 'The test set has no cases.' };
   }
   const c = comparison ?? DEFAULT_COMPARISON;
+  if (c.versions !== undefined && 'agentId' in target) {
+    return { kind: 'err', message: VERSIONS_NEED_A_FLOW };
+  }
   if (c.baseline !== 'recorded') {
     return { kind: 'err', message: "Only `baseline: 'recorded'` runs today." };
   }
@@ -180,7 +212,9 @@ export function createJudgedDispatcher(options: JudgedDispatcherOptions): EvalRu
     validate: validateComparison,
     async dispatch(ctx): Promise<DispatchResult> {
       const comparison = ctx.comparison ?? DEFAULT_COMPARISON;
-      const all = await allCases(options.cases, ctx);
+      const stored = await allCases(options.cases, ctx);
+      const all =
+        comparison.classWeights === 'restricted-only' ? stored.map(restrictedOnly) : stored;
       if (ctx.dryRun) {
         return { result: { dryRun: true, cases: all.length, comparison } };
       }
@@ -192,7 +226,8 @@ export function createJudgedDispatcher(options: JudgedDispatcherOptions): EvalRu
         results.push(result);
         ctx.onProgress(result as unknown as Readonly<Record<string, unknown>>);
       }
-      const summary = summarize(ctx, comparison, all, results, [...models.values()]);
+      const pinsDigest = await candidatePins(options.agents, ctx);
+      const summary = summarize(ctx, comparison, all, results, [...models.values()], pinsDigest);
       return {
         result: { summary, perCase: results },
         ...(ctx.abortSignal.aborted && { error: 'cancelled' }),
@@ -337,6 +372,8 @@ async function invokeCase(
         evalRunId: ctx.runId as unknown as string,
       },
       ...(judgedCase.subject.kind === 'agent' && { history: judgedCase.context?.history ?? [] }),
+      ...(!('agentId' in ctx.target) &&
+        ctx.comparison?.versions !== undefined && { versions: ctx.comparison.versions }),
     });
   } catch (cause) {
     return { error: cause instanceof Error ? cause.message : String(cause) };
@@ -436,6 +473,7 @@ function summarize(
   cases: readonly JudgedEvalCase[],
   results: readonly JudgedCaseResult[],
   models: readonly { providerId: string; model: string; runs: number }[],
+  pinsDigest: string | undefined,
 ): JudgedComparisonSummary {
   const errors = results.filter((r) => r.error !== undefined).length;
   const stopped = results.filter((r) => r.stopped !== undefined).length;
@@ -467,7 +505,7 @@ function summarize(
           : 'failed',
     completedAt: new Date().toISOString(),
     suite: { id: ctx.suite.id, version: ctx.suite.version },
-    candidate: candidateOf(ctx.target),
+    candidate: candidateOf(ctx.target, ctx.comparison?.versions, pinsDigest),
     baseline: {
       kind: 'recorded',
       versions: [...versions.values()].map(
@@ -484,6 +522,7 @@ function summarize(
     errors,
     stopped,
     reads: comparison.reads,
+    classWeights: comparison.classWeights ?? 'as-recorded',
     sampling: { models },
     repetitions: comparison.repetitions,
     metrics: {
@@ -500,8 +539,60 @@ function summarize(
   };
 }
 
-function candidateOf(target: AgentRef | FlowRef): ComparisonCandidate {
+/**
+ * A case as a `restricted-only` comparison counts it: each item at its
+ * restricted judgments' weights; an item with none is left out, so it
+ * counts as unjudged.
+ */
+function restrictedOnly(c: JudgedEvalCase): JudgedEvalCase {
+  return {
+    ...c,
+    items: c.items.flatMap((item) =>
+      item.restricted !== undefined && item.restricted.totalWeight > 0
+        ? [
+            {
+              ...item,
+              yesWeight: item.restricted.yesWeight,
+              totalWeight: item.restricted.totalWeight,
+            },
+          ]
+        : [],
+    ),
+  };
+}
+
+/** The agent candidate's `pinsDigest`, from the registry. */
+async function candidatePins(
+  agents: JudgedDispatcherOptions['agents'],
+  ctx: DispatchContext,
+): Promise<string | undefined> {
+  if (agents === undefined || !('agentId' in ctx.target) || ctx.target.version === undefined) {
+    return undefined;
+  }
+  const found = await agents.getVersion({
+    tenantId: ctx.tenantId,
+    agentId: ctx.target.agentId,
+    version: ctx.target.version,
+  });
+  return found?.pinsDigest;
+}
+
+function candidateOf(
+  target: AgentRef | FlowRef,
+  versions: FlowVersionOverrides | undefined,
+  pinsDigest?: string,
+): ComparisonCandidate {
   return 'agentId' in target
-    ? { kind: 'agent', agentId: target.agentId as unknown as string, version: target.version ?? '' }
-    : { kind: 'flow', flowId: target.flowId as unknown as string, version: target.version ?? '' };
+    ? {
+        kind: 'agent',
+        agentId: target.agentId as unknown as string,
+        version: target.version ?? '',
+        ...(pinsDigest !== undefined && { pinsDigest }),
+      }
+    : {
+        kind: 'flow',
+        flowId: target.flowId as unknown as string,
+        version: target.version ?? '',
+        ...(versions !== undefined && { versions }),
+      };
 }

package/src/judgment-binding.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
+import { REVIEWER_ROLE_RANK, type ReviewerRole } from '@kindgi/authz';
 import type { Cursor, ListScope, ProjectId, TenantId } from '@kindgi/types';
 
 /**
@@ -77,6 +78,54 @@ export type JudgeClassScope =
 export const JUDGE_CLASS_SCOPE_KINDS = ['tenant', 'project', 'agent'] as const;
 export type JudgeClassScopeKind = (typeof JUDGE_CLASS_SCOPE_KINDS)[number];
 
+/**
+ * Who may assert a judge class (T200): every part that's set must hold.
+ * Absent: anyone who may judge the run may assert the class, as before.
+ * A class with one is *restricted*; a judgment recorded while it is
+ * carries `restricted`, and a comparison weighted `restricted-only`
+ * counts only those.
+ */
+export interface JudgeClassAssertableBy {
+  /** The caller's reviewer role is at least this (its token's, or the roster's). */
+  readonly minReviewerRole?: ReviewerRole;
+  /** Users, service tokens, or both. */
+  readonly principalKinds?: readonly ('user' | 'service')[];
+  /** Only these principals: user ids, or service token ids. */
+  readonly principalIds?: readonly string[];
+}
+
+/** Who asserts a judgment, as `JudgeClassAssertableBy` checks it. */
+export interface JudgeClassAsserter {
+  readonly kind: 'user' | 'service';
+  readonly id: string;
+  /** The caller's reviewer role; absent for a caller who isn't a reviewer. */
+  readonly reviewerRole?: ReviewerRole;
+}
+
+/** Why `asserter` may not assert a class with `assertableBy`, or `undefined` when they may. */
+export function whyNotAssertable(
+  assertableBy: JudgeClassAssertableBy,
+  asserter: JudgeClassAsserter,
+): string | undefined {
+  if (
+    assertableBy.principalKinds !== undefined &&
+    !assertableBy.principalKinds.includes(asserter.kind)
+  ) {
+    return `only ${assertableBy.principalKinds.map((k) => (k === 'user' ? 'users' : 'service tokens')).join(' and ')} may assert it`;
+  }
+  if (assertableBy.principalIds !== undefined && !assertableBy.principalIds.includes(asserter.id)) {
+    return "it's restricted to named people or tokens, and you aren't one of them";
+  }
+  if (assertableBy.minReviewerRole !== undefined) {
+    const need = assertableBy.minReviewerRole;
+    const role = asserter.reviewerRole;
+    if (role === undefined || REVIEWER_ROLE_RANK[role] < REVIEWER_ROLE_RANK[need]) {
+      return `it needs a ${need} reviewer or above${role === undefined ? ", and you aren't a reviewer" : `; you're a ${role} reviewer`}`;
+    }
+  }
+  return undefined;
+}
+
 export interface JudgeClass {
   readonly id: string;
   readonly tenantId: TenantId;
@@ -86,6 +135,8 @@ export interface JudgeClass {
   /** How much a judgment of this class counts (≥ 0); an unclassified judgment counts 1. */
   readonly weight: number;
   readonly description?: string;
+  /** Who may assert it; absent: anyone who may judge the run (T200). */
+  readonly assertableBy?: JudgeClassAssertableBy;
   readonly createdAt: string;
   readonly updatedAt: string;
   /** Set when the class was retired. */
@@ -98,6 +149,7 @@ export interface JudgeClassCreateInput {
   readonly name: string;
   readonly weight: number;
   readonly description?: string;
+  readonly assertableBy?: JudgeClassAssertableBy;
 }
 
 export type JudgeClassCreateOutcome =
@@ -128,6 +180,8 @@ export interface JudgeClassUpdateInput {
   readonly judgeClassId: string;
   readonly weight?: number;
   readonly description?: string;
+  /** Who may assert it; `null` lifts the restriction. Absent: unchanged. */
+  readonly assertableBy?: JudgeClassAssertableBy | null;
 }
 
 /** Whether a class's scope covers a run in `projectId` whose subject is `subject`. */
@@ -189,6 +243,12 @@ export interface Judgment {
   readonly reason?: string;
   /** The judge's class; absent for an unclassified judgment (weight 1). */
   readonly judgeClassId?: string;
+  /**
+   * Set when the class was restricted (`assertableBy`) when the judgment
+   * was recorded, so the judge was checked against it. A restriction added
+   * or lifted later doesn't change it (T200).
+   */
+  readonly restricted?: true;
   readonly assertedBy: JudgmentAssertedBy;
   /** The app's opaque id for its end user who judged, when an app judged on their behalf. */
   readonly participantId?: string;
@@ -292,6 +352,8 @@ export interface JudgmentRecordInput {
   readonly verdict: Verdict;
   readonly reason?: string;
   readonly judgeClassId?: string;
+  /** The class was restricted, and the judge met it (see `Judgment.restricted`). */
+  readonly restricted?: true;
   readonly assertedBy: JudgmentAssertedBy;
   readonly participantId?: string;
 }

package/src/live-version-binding.ts

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type {
+  Cursor,
+  LiveScope,
+  OrgId,
+  ProjectId,
+  Result,
+  ScopeSegment,
+  Semver,
+  TenantId,
+  Timestamp,
+} from '@kindgi/types';
+
+import type { GatePolicyBinding, GatePolicyRef } from './gate-policy-binding.js';
+import type { GateApproval, GateCheck } from './gate.js';
+
+/**
+ * Live versions of agents: which version serves a scope, and the
+ * promotions that put it there (evals step 4). A run that names no
+ * version takes the most specific live version that covers it (a
+ * segment path, then its project, its org, the tenant), else the latest
+ * registered one, as before anything is pinned.
+ */
+
+/** What a run's version is resolved for: its project (and org) and its segment path. */
+export interface LiveResolveInput {
+  readonly tenantId: TenantId;
+  readonly agentId: string;
+  /** Absent → only the org's pin (with `orgId`) and the tenant-wide pin apply. */
+  readonly projectId?: ProjectId;
+  /**
+   * The project's org, when it has one (the resolver may look it up from
+   * `projectId` itself). Without `projectId`: an org scope's own
+   * coordinates, as the promotion gate resolves what serves an org.
+   */
+  readonly orgId?: OrgId;
+  /** Coarse to fine (needs `projectId`); a segment pin covers every path that starts with its own. */
+  readonly segments?: readonly ScopeSegment[];
+}
+
+export interface LiveResolution {
+  readonly version: Semver;
+  /** The pin that matched. */
+  readonly scope: LiveScope;
+}
+
+export interface LivePin {
+  readonly agentId: string;
+  readonly scope: LiveScope;
+  readonly version: Semver;
+  /** The promotion that set it. */
+  readonly promotionId: string;
+  readonly setAt: Timestamp;
+}
+
+export interface LiveVersionBinding {
+  /** The most specific live version covering the input; `null` when none is pinned on the way up. */
+  resolve(input: LiveResolveInput): Promise<LiveResolution | null>;
+  /** Every pin of an agent. */
+  list(input: { readonly tenantId: TenantId; readonly agentId: string }): Promise<
+    readonly LivePin[]
+  >;
+}
+
+/** Who asked: the request's principal (a user, or a service token). */
+export interface PromotionActor {
+  readonly kind: 'user' | 'service';
+  readonly id: string;
+}
+
+export type PromotionAction = 'promote' | 'rollback' | 'unpin';
+
+/**
+ * Where a promotion request stands. Only `promote` rows have one; rollback
+ * and unpin are immediate. A request's status changes once, from
+ * `pending-approval` to its final state.
+ */
+export type PromotionStatus =
+  /** The version is live for the scope. */
+  | 'promoted'
+  /** The gate passed; a reviewer's approval is open. The live version is unchanged. */
+  | 'pending-approval'
+  /** The gate failed (`checks` say why). The live version is unchanged. */
+  | 'refused'
+  /** Approved, but the scope's live version or policy changed meanwhile: check again. */
+  | 'superseded'
+  /** The reviewer rejected it. */
+  | 'rejected'
+  /** The approval expired undecided. */
+  | 'expired';
+
+/**
+ * One change of a scope's live version, kept for good (the audit trail):
+ * what was live before, what is after, who asked and why.
+ */
+export interface Promotion {
+  readonly id: string;
+  readonly agentId: string;
+  readonly scope: LiveScope;
+  readonly action: PromotionAction;
+  /** The scope's own pin before; `null` when it had none. */
+  readonly fromVersion: Semver | null;
+  /** The scope's own pin after; `null` after an unpin. */
+  readonly toVersion: Semver | null;
+  readonly requestedBy: PromotionActor;
+  readonly reason?: string;
+  /** The comparison the change was judged on, when there was one. */
+  readonly evalRunId?: string;
+  readonly createdAt: Timestamp;
+  /** A `promote` row's state; absent on a promotion made before gates (`promoted`). */
+  readonly status?: PromotionStatus;
+  /** The gate policy that applied; `null` when none did. Absent before gates. */
+  readonly policy?: GatePolicyRef | null;
+  /** The gate's checks, as they ran. */
+  readonly checks?: readonly GateCheck[];
+  /** The approval a `pending-approval` promotion waits on (kept once decided). */
+  readonly approvalId?: string;
+  /** When a `pending-approval` promotion reached its final state. */
+  readonly resolvedAt?: Timestamp;
+}
+
+export type PromotionErrorCode =
+  /** The version isn't registered for this agent, or was unregistered. */
+  | 'agent-version-not-found'
+  /** The scope names an org or project the tenant doesn't have. */
+  | 'scope-invalid'
+  /** Rollback: the scope has no earlier live version to go back to. */
+  | 'nothing-to-roll-back'
+  /** Unpin or rollback: the scope has no pin of its own. */
+  | 'not-pinned'
+  /** The scope's live version changed while the gate ran: check again. */
+  | 'promotion-superseded'
+  /**
+   * Unpin or rollback: it would leave a scope a gate policy applies to
+   * resolving to the latest version, where publishing goes live ungated.
+   */
+  | 'gate-policy-needs-pin'
+  | 'persistence-error';
+
+export interface PromotionError {
+  readonly code: PromotionErrorCode;
+  readonly message: string;
+}
+
+export interface PromoteInput {
+  readonly tenantId: TenantId;
+  readonly agentId: string;
+  readonly version: Semver;
+  readonly scope: LiveScope;
+  readonly requestedBy: PromotionActor;
+  readonly reason?: string;
+  readonly evalRunId?: string;
+}
+
+/**
+ * A promotion with the gate's verdict, recorded as one request: refused,
+ * waiting for approval, or promoted. The route runs the gate; the
+ * binding records the outcome atomically.
+ */
+export interface PromotionRequestInput extends PromoteInput {
+  readonly gate: {
+    readonly policy: GatePolicyRef | null;
+    readonly checks: readonly GateCheck[];
+    readonly passed: boolean;
+    /** A passing promotion waits for this approval instead of going live. */
+    readonly approval?: GateApproval;
+    /**
+     * What served the scope when the gate ran. A binding refuses with
+     * `promotion-superseded` when it no longer does, and an approved
+     * promotion whose scope moved on becomes `superseded`.
+     */
+    readonly servingVersion: Semver;
+  };
+}
+
+export interface RollbackInput {
+  readonly tenantId: TenantId;
+  readonly agentId: string;
+  readonly scope: LiveScope;
+  /** Back to this earlier version; absent → the scope's previous live version. */
+  readonly toVersion?: Semver;
+  readonly requestedBy: PromotionActor;
+  readonly reason?: string;
+}
+
+export interface UnpinInput {
+  readonly tenantId: TenantId;
+  readonly agentId: string;
+  readonly scope: LiveScope;
+  readonly requestedBy: PromotionActor;
+  readonly reason?: string;
+}
+
+export interface ListPromotionsInput {
+  readonly tenantId: TenantId;
+  readonly agentId: string;
+  /** Only this scope's history. */
+  readonly scope?: LiveScope;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export interface PromotionBinding {
+  /** Make `version` live for `scope`. The version must be registered and active. */
+  promote(input: PromoteInput): Promise<Result<Promotion, PromotionError>>;
+  /**
+   * Record a gated promotion request (evals step 4b): `refused` when the
+   * gate failed, `pending-approval` (opening a HITL approval, subject
+   * `agent-promotion`) when it passed and the policy wants an approval,
+   * else `promoted`. Optional: without it, the route refuses a promotion
+   * a gate policy applies to (`501`), rather than promoting ungated.
+   */
+  request?(input: PromotionRequestInput): Promise<Result<Promotion, PromotionError>>;
+  /** Back to the scope's previous live version, or a named earlier one. */
+  rollback(input: RollbackInput): Promise<Result<Promotion, PromotionError>>;
+  /**
+   * Remove the scope's own pin: it falls back to the next scope up. With
+   * gate policies, `gate-policy-needs-pin` when that would leave a gated
+   * scope resolving to the latest version.
+   */
+  unpin(input: UnpinInput): Promise<Result<Promotion, PromotionError>>;
+  list(input: ListPromotionsInput): Promise<{
+    readonly data: readonly Promotion[];
+    readonly nextCursor?: Cursor;
+  }>;
+  get(tenantId: TenantId, promotionId: string): Promise<Promotion | null>;
+}
+
+/** The bindings behind an agent's live versions and promotions (`createApp({ agentReleases })`). */
+export interface AgentReleaseBindings {
+  readonly live: LiveVersionBinding;
+  readonly promotions: PromotionBinding;
+  /** Gate policies (evals step 4b). Absent: no gates, every promotion goes through as before. */
+  readonly gatePolicies?: GatePolicyBinding;
+}