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

package/src/middleware/idempotency.ts

@@ -1,16 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 
-import type { MiddlewareHandler } from 'hono';
+import type { Context, MiddlewareHandler } from 'hono';
 
 import type { TenantId } from '@kindgi/types';
 
+import { callerRef } from '../caller.js';
 import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
 
 /**
- * Idempotency-key store: `(tenantId, route, key) → cached response`,
+ * Idempotency-key store: `(tenantId, caller, route, key) → cached response`,
  * cached for `ttlMs` (default 24h per API-ROUTE-CONVENTIONS.md §3.1).
  *
  * Injected into the middleware so deployments can plug in a durable
@@ -20,38 +22,117 @@ import { statusFor, toWireError } from '../errors.js';
  */
 export interface IdempotencyStore {
   get(key: string): Promise<StoredIdempotencyEntry | null>;
+  /** Store an answer. It replaces a hold on the key, never a stored answer: the first stays. */
   set(key: string, entry: StoredIdempotencyEntry): Promise<void>;
+  /**
+   * Hold a key while its request runs (T349), so a repeat sent meanwhile
+   * is answered 409 `idempotency-key-in-flight` instead of running the
+   * operation again. Optional: a store without holds holds nothing, and
+   * such a repeat runs again (the behaviour before 0.1.5).
+   */
+  readonly holds?: IdempotencyHolds;
 }
 
+/** A store's holds: all three or none. */
+export interface IdempotencyHolds {
+  /** Take the key for `hold.holder`, unless an unexpired hold or a stored answer has it. */
+  hold(key: string, hold: IdempotencyHold): Promise<IdempotencyHoldOutcome>;
+  /** Extend the holder's hold: its request still runs. */
+  renew(key: string, holder: string, expiresAt: number): Promise<void>;
+  /** Drop the holder's hold: its request ended with nothing to replay. */
+  release(key: string, holder: string): Promise<void>;
+}
+
+export interface IdempotencyHold {
+  /** Who holds it: one id per request. */
+  readonly holder: string;
+  readonly bodyHash: string;
+  readonly expiresAt: number;
+}
+
+export type IdempotencyHoldOutcome =
+  | { readonly kind: 'held' }
+  | { readonly kind: 'in-flight'; readonly bodyHash: string }
+  | { readonly kind: 'stored'; readonly entry: StoredIdempotencyEntry };
+
 export interface StoredIdempotencyEntry {
   readonly bodyHash: string;
   readonly status: number;
   readonly contentType: string;
+  /** The answer's body; empty when it's `withheld`. */
   readonly bodyText: string;
   readonly expiresAt: number;
+  /**
+   * The answer carried a secret (`withholdFromReplay`), so only that the
+   * request succeeded is kept: a repeat is answered 409
+   * `idempotency-key-replay-withheld`, never the secret. Optional: a store
+   * that doesn't keep it stores the empty body, and a repeat replays that.
+   */
+  readonly withheld?: boolean;
+  /** When the answer was stored (ms since the epoch), for the withheld 409. */
+  readonly storedAt?: number;
+}
+
+/**
+ * For a route whose answer carries a secret (an API key, a session token,
+ * a signing secret): the Idempotency-Key middleware keeps that the request
+ * succeeded and when, never the answer. A repeat with the same key gets 409
+ * `idempotency-key-replay-withheld` instead of the secret, and instead of
+ * running again (which would make a second one). Call it before answering.
+ */
+export function withholdFromReplay(c: Context<AppEnv>): void {
+  c.set('idempotencyWithhold', true);
 }
 
 /** Simple in-memory store with lazy expiry — swap for a DB store in prod. */
 export function createInMemoryIdempotencyStore(): IdempotencyStore {
   const table = new Map<string, StoredIdempotencyEntry>();
+  const held = new Map<string, IdempotencyHold>();
+  const stored = (key: string): StoredIdempotencyEntry | null => {
+    const hit = table.get(key);
+    if (hit === undefined) return null;
+    if (hit.expiresAt <= Date.now()) {
+      table.delete(key);
+      return null;
+    }
+    return hit;
+  };
   return {
     async get(key) {
-      const hit = table.get(key);
-      if (hit === undefined) return null;
-      if (hit.expiresAt <= Date.now()) {
-        table.delete(key);
-        return null;
-      }
-      return hit;
+      return stored(key);
     },
     async set(key, entry) {
-      table.set(key, entry);
+      held.delete(key);
+      if (stored(key) === null) table.set(key, entry);
+    },
+    holds: {
+      async hold(key, hold) {
+        const entry = stored(key);
+        if (entry !== null) return { kind: 'stored', entry };
+        const current = held.get(key);
+        if (current !== undefined && current.expiresAt > Date.now()) {
+          return { kind: 'in-flight', bodyHash: current.bodyHash };
+        }
+        held.set(key, hold);
+        return { kind: 'held' };
+      },
+      async renew(key, holder, expiresAt) {
+        const current = held.get(key);
+        if (current?.holder === holder) held.set(key, { ...current, expiresAt });
+      },
+      async release(key, holder) {
+        if (held.get(key)?.holder === holder) held.delete(key);
+      },
     },
   };
 }
 
 const MUTATING_METHODS: ReadonlySet<string> = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/** How long a hold lasts unless renewed; renewed every third of it while the request runs. */
+const DEFAULT_HOLD_MS = 30 * 1000;
+/** What a repeat in flight is told to wait, in seconds. */
+const IN_FLIGHT_RETRY_AFTER_S = 5;
 
 /**
  * Idempotency-Key middleware per API-ROUTE-CONVENTIONS.md §3.1.
@@ -68,16 +149,30 @@ const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
  *   nothing, and a failure (5xx) may be transient: neither is stored, so
  *   a retry with the same key after fixing the cause runs again instead
  *   of replaying the old error.
+ * - With a store that holds keys (`store.holds`, T349): the key is held
+ *   while the handler runs (for `holdMs`, renewed every third of it), so
+ *   a repeat sent meanwhile gets 409 `idempotency-key-in-flight` with
+ *   `Retry-After`, or `idempotency-key-body-mismatch` for another body,
+ *   instead of running the operation again. The hold becomes the stored
+ *   answer, or is released when nothing is stored. A crashed request's
+ *   hold lapses within `holdMs`.
+ *
+ * The middleware sits AFTER auth so `tenantId` is available. The cache
+ * key is the tenant, the caller (`user:…`, `service_account:…`, else the
+ * key or session it came with), the route and the key: someone else in
+ * the tenant who sends the same key and body runs the request themselves,
+ * and never gets another caller's answer (T392).
  *
- * The middleware sits AFTER auth so `tenantId` is available; the
- * cache key is namespaced by tenant so callers can't collide across
- * tenants.
+ * A route whose answer carries a secret calls `withholdFromReplay`: its
+ * answer isn't kept, only that it succeeded (status, when). A repeat with
+ * the same key and body gets 409 `idempotency-key-replay-withheld`.
  */
 export function idempotencyMiddleware(
   store: IdempotencyStore,
-  opts: { ttlMs?: number } = {},
+  opts: { ttlMs?: number; holdMs?: number } = {},
 ): MiddlewareHandler {
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const holdMs = opts.holdMs ?? DEFAULT_HOLD_MS;
   return async (c, next) => {
     if (!MUTATING_METHODS.has(c.req.method.toUpperCase())) {
       return next();
@@ -96,51 +191,143 @@ export function idempotencyMiddleware(
     }
 
     const bodyText = await readRawBody(c.req.raw);
-    const bodyHash = hashBody(bodyText);
-    const cacheKey = `${tenantId}|${c.req.method.toUpperCase()}:${c.req.path}|${rawKey}`;
+    const bodyHash = sha256Hex(bodyText);
+    const cacheKey = `${tenantId}|${callerKey(c as Context<AppEnv>)}|${c.req.method.toUpperCase()}:${c.req.path}|${rawKey}`;
     const hit = await store.get(cacheKey);
+    if (hit !== null) return replay(c, hit, bodyHash, requestId, ttlMs);
 
-    if (hit !== null) {
-      if (hit.bodyHash !== bodyHash) {
-        c.status(statusFor('idempotency-key-body-mismatch') as never);
+    const { holds } = store;
+    const holder = randomUUID();
+    if (holds !== undefined) {
+      const held = await holds.hold(cacheKey, {
+        holder,
+        bodyHash,
+        expiresAt: Date.now() + holdMs,
+      });
+      if (held.kind === 'stored') return replay(c, held.entry, bodyHash, requestId, ttlMs);
+      if (held.kind === 'in-flight') {
+        if (held.bodyHash !== bodyHash) return bodyMismatch(c, requestId);
+        c.header('Retry-After', String(IN_FLIGHT_RETRY_AFTER_S));
+        c.status(statusFor('idempotency-key-in-flight') as never);
         return c.json(
           toWireError(
             {
-              code: 'idempotency-key-body-mismatch',
+              code: 'idempotency-key-in-flight',
               message:
-                'Idempotency-Key was reused with a different request body. Use a fresh key or the original body.',
+                "A request with this Idempotency-Key is still running. Retry after it answers (Retry-After), and you'll get its answer.",
             },
             requestId,
           ),
         );
       }
-      return c.body(hit.bodyText, hit.status as never, {
-        'Content-Type': hit.contentType,
-        'X-Idempotent-Replay': 'true',
-      });
     }
 
     // Re-attach the buffered body so downstream handlers reading
     // `c.req.json()` see the same bytes.
     if (bodyText.length > 0) rebindBody(c, bodyText);
-    await next();
-
-    const res = c.res;
-    // Only what took effect is replayed; see the doc above.
-    if (res.status >= 400) return;
-    const savedBody = await res.clone().text();
-    const contentType = res.headers.get('Content-Type') ?? 'application/octet-stream';
-    await store.set(cacheKey, {
-      bodyHash,
-      status: res.status,
-      contentType,
-      bodyText: savedBody,
-      expiresAt: Date.now() + ttlMs,
-    });
-    return;
+    const renewal =
+      holds === undefined
+        ? undefined
+        : setInterval(
+            () => {
+              holds.renew(cacheKey, holder, Date.now() + holdMs).catch(() => undefined);
+            },
+            Math.max(1, Math.floor(holdMs / 3)),
+          );
+    renewal?.unref?.();
+    let answered = false;
+    try {
+      await next();
+
+      const res = c.res;
+      // Only what took effect is replayed; see the doc above.
+      if (res.status >= 400) return;
+      const withheld = (c as Context<AppEnv>).get('idempotencyWithhold') === true;
+      const savedBody = withheld ? '' : await res.clone().text();
+      const contentType = res.headers.get('Content-Type') ?? 'application/octet-stream';
+      const now = Date.now();
+      await store.set(cacheKey, {
+        bodyHash,
+        status: res.status,
+        contentType,
+        bodyText: savedBody,
+        expiresAt: now + ttlMs,
+        ...(withheld && { withheld: true }),
+        storedAt: now,
+      });
+      answered = true;
+    } finally {
+      if (renewal !== undefined) clearInterval(renewal);
+      // Nothing stored (a refusal, a failure, a throw): let a retry run.
+      if (!answered && holds !== undefined) {
+        await holds.release(cacheKey, holder).catch(() => undefined);
+      }
+    }
   };
 }
 
+/**
+ * Who the request comes from, for the cache key: the caller's principal
+ * (`user:…`, `service_account:…`; an API key with neither is its own
+ * service account), else the session it came with, else the credential
+ * itself (`token:` and the first 16 hex of its sha256: one bucket per
+ * credential, never a shared one, and nothing a reader could use).
+ */
+function callerKey(c: Context<AppEnv>): string {
+  const ref = callerRef(c);
+  if (ref !== undefined) return ref;
+  const sessionId = c.get('sessionId');
+  if (sessionId !== undefined) return `session:${sessionId as unknown as string}`;
+  return `token:${sha256Hex(c.req.header('authorization') ?? '').slice(0, 16)}`;
+}
+
+/**
+ * A stored answer, replayed; or the refusal for the same key with another
+ * body; or, for an answer that carried a secret, what succeeded and when.
+ */
+function replay(
+  c: Context,
+  hit: StoredIdempotencyEntry,
+  bodyHash: string,
+  requestId: string,
+  ttlMs: number,
+) {
+  if (hit.bodyHash !== bodyHash) return bodyMismatch(c, requestId);
+  if (hit.withheld === true) {
+    const at = new Date(hit.storedAt ?? hit.expiresAt - ttlMs).toISOString();
+    c.status(statusFor('idempotency-key-replay-withheld') as never);
+    return c.json(
+      toWireError(
+        {
+          code: 'idempotency-key-replay-withheld',
+          message: `The request with this Idempotency-Key succeeded (${hit.status}, at ${at}). Its answer carried a secret, which isn't kept, so it can't be sent again: read what it made (for an API key, \`GET /v1/tokens\`), or make a new one with a fresh key.`,
+          status: hit.status,
+          at,
+        },
+        requestId,
+      ),
+    );
+  }
+  return c.body(hit.bodyText, hit.status as never, {
+    'Content-Type': hit.contentType,
+    'X-Idempotent-Replay': 'true',
+  });
+}
+
+function bodyMismatch(c: Context, requestId: string) {
+  c.status(statusFor('idempotency-key-body-mismatch') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'idempotency-key-body-mismatch',
+        message:
+          'Idempotency-Key was reused with a different request body. Use a fresh key or the original body.',
+      },
+      requestId,
+    ),
+  );
+}
+
 async function readRawBody(req: Request): Promise<string> {
   const method = req.method.toUpperCase();
   if (method === 'GET' || method === 'HEAD') return '';
@@ -151,8 +338,8 @@ async function readRawBody(req: Request): Promise<string> {
   }
 }
 
-function hashBody(body: string): string {
-  return createHash('sha256').update(body).digest('hex');
+function sha256Hex(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
 }
 
 function rebindBody(c: { req: { raw: Request } }, body: string): void {

package/src/middleware/key-project.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
+
+const PROJECT_PATH_RE = /\/projects\/([^/]+)/;
+const WRITE_METHODS: ReadonlySet<string> = new Set(['POST', 'PUT', 'PATCH']);
+
+/**
+ * A key limited to a project (`projectId` at mint) is refused, `403
+ * key-project-mismatch`, on a request that names another project in any
+ * of the places a request names one:
+ *
+ * - the path: `/projects/<id>/…`;
+ * - the query: `?projectId=<id>`, or `?scopeKind=project&scopeId=<id>`;
+ * - a JSON write body: `projectId`, or `scope.projectId`.
+ *
+ * Requests from any other caller pass untouched. What the key may do in
+ * its own project is the authorizer's to decide, under the principal's
+ * grants.
+ */
+export function refuseOtherProjectForKey(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const keyProject = c.get('tokenProjectId');
+    if (keyProject === undefined) return next();
+    for (const named of await projectsNamed(c.req)) {
+      if (named !== keyProject) {
+        c.status(statusFor('key-project-mismatch') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'key-project-mismatch',
+              message: `This API key is limited to project ${keyProject}; the request names project ${named}`,
+              keyProjectId: keyProject,
+              projectId: named,
+            },
+            c.get('requestId'),
+          ),
+        );
+      }
+    }
+    return next();
+  };
+}
+
+type RequestLike = {
+  readonly path: string;
+  readonly method: string;
+  query(name: string): string | undefined;
+  json(): Promise<unknown>;
+};
+
+/** Every project id the request names, in path, query and body. */
+async function projectsNamed(req: RequestLike): Promise<string[]> {
+  const named: string[] = [];
+  const inPath = PROJECT_PATH_RE.exec(req.path)?.[1];
+  if (inPath !== undefined) named.push(decodeURIComponent(inPath));
+  const inQuery = req.query('projectId');
+  if (inQuery !== undefined && inQuery !== '') named.push(inQuery);
+  const scopeId = req.query('scopeId');
+  if (req.query('scopeKind') === 'project' && scopeId !== undefined) named.push(scopeId);
+  if (WRITE_METHODS.has(req.method)) named.push(...(await projectsInBody(req)));
+  return named;
+}
+
+/** `projectId` and `scope.projectId` in a JSON body; none when it isn't JSON. */
+async function projectsInBody(req: RequestLike): Promise<string[]> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return [];
+  }
+  if (body === null || typeof body !== 'object') return [];
+  const b = body as { readonly projectId?: unknown; readonly scope?: unknown };
+  const named: string[] = [];
+  if (typeof b.projectId === 'string') named.push(b.projectId);
+  const scope = b.scope as { readonly projectId?: unknown } | null | undefined;
+  if (scope !== null && typeof scope === 'object' && typeof scope.projectId === 'string') {
+    named.push(scope.projectId);
+  }
+  return named;
+}

package/src/middleware/principal.ts

@@ -28,6 +28,7 @@ export function principalMiddleware(): MiddlewareHandler<AppEnv> {
     const userId = c.get('userId');
     const tokenId = c.get('tokenId');
     const sessionId = c.get('sessionId');
+    const keyServiceAccount = c.get('serviceAccountId');
 
     if (tenantId === undefined) {
       // Bearer middleware didn't populate — either the route is
@@ -37,12 +38,15 @@ export function principalMiddleware(): MiddlewareHandler<AppEnv> {
       return next();
     }
 
-    // A user when the token names one; otherwise a service account: a
-    // durable API key's id, or else the session id (which uniquely
-    // identifies the token record). With none of them, leave `principal`
-    // unset; `authorize()` treats that as "no principal" and 403s cleanly.
+    // A user when the token names one; otherwise a service account: the
+    // one an API key acts for, else the key's own id (a store built before
+    // principals), else the session id (which uniquely identifies the
+    // token record). With none of them, leave `principal` unset;
+    // `authorize()` treats that as "no principal" and 403s cleanly.
     const serviceAccountId =
-      (tokenId as unknown as string | undefined) ?? (sessionId as unknown as string | undefined);
+      keyServiceAccount ??
+      (tokenId as unknown as string | undefined) ??
+      (sessionId as unknown as string | undefined);
     if (userId === undefined && serviceAccountId === undefined) {
       return next();
     }

package/src/middleware/project-ref.ts

@@ -33,6 +33,9 @@ export const PROJECT_REF_ROUTES: readonly string[] = [
   '/eval-suites/:suiteId/versions/from-judgments',
   '/eval-suites/:suiteId/runs',
   '/blocks',
+  '/schedules',
+  '/service-accounts/:serviceAccountId/grant',
+  '/service-accounts/:serviceAccountId/ungrant',
 ];
 
 /**

package/src/openapi/generate.ts

@@ -49,6 +49,8 @@ const DEFAULT_SERVERS: readonly OpenApiServer[] = [
 const TAG_DESCRIPTIONS: Readonly<Record<string, string>> = {
   system: 'Health + spec discovery.',
   runs: 'Run lifecycle (start, list, get, cancel, resume, journal, stream).',
+  'export-signing-keys':
+    'The public keys this deployment signs its exports with (audit bundles, provenance, compliance evidence): what a verifier pins.',
   'signing-keys':
     'The deployment trust list: the public keys whose signatures `POST /v1/deployments` accepts. Revoked keys stay readable for audit.',
   tokens:
@@ -69,7 +71,7 @@ const TAG_DESCRIPTIONS: Readonly<Record<string, string>> = {
   proposals:
     'Supervisor fix-proposal lifecycle (draft, dry-run, submit-review, apply, rollback, withdraw — caller-plugged binding wraps the supervisor).',
   provenance:
-    'Causal DAG readback + signed exports (list, get, export — signing is caller-plugged via `SigningKeyBinding`).',
+    "Causal DAG readback + signed exports (list, get, export), signed with the deployment's export key.",
   artifacts:
     'Blob storage (list metadata, multipart upload, streaming download, HEAD, delete). Caller-plugged via `BlobStorageBinding` (from `@kindgi/blob-binding`).',
   capabilities:
@@ -100,7 +102,7 @@ const TAG_DESCRIPTIONS: Readonly<Record<string, string>> = {
   deployments:
     'Signed pack deployments (register, list, get). The single wire surface that lands a signed OCI image + index.json into the platform. Register runs a six-step atomic transaction: Ed25519 signature verify over the canonical `{imageDigest, artifactVersion, indexHash, tenantId, publishedAt}` envelope, tenant-scoped trust-list check via `SigningKeyRegistryBinding`, image pullability + `/app/index.json` sha256 match via `ImageRegistryBinding`, per-primitive manifest validation, registry upserts (tools + guardrails + agents + flows), append-only deployment ledger row via `DeploymentBinding`. All-or-nothing rollback on any failure; digest-based idempotency (redeploying the same image returns the existing record). Records are immutable — rollback = re-register the previous digest.',
   compliance:
-    'Compliance-evidence readback + signed exports (list, get, export). Reads are a classification lens over `AuditEventBinding`; only classifier-marked `exportable` kinds appear on the wire. Signed export is caller-plugged via `SigningKeyBinding` — deployments without a signing key get `404 signing-not-configured`. Bundle envelope matches `provenance.export` + audit-bundle byte-for-byte so verifiers reuse one `verifyEd25519` wrapper across all three surfaces. Redaction happens when evidence is generated, not at the export boundary — records are stored already redacted.',
+    'Compliance-evidence readback + signed exports (list, get, export). Reads are a classification lens over `AuditEventBinding`; only classifier-marked `exportable` kinds appear on the wire. A signed export is signed with the export signing key of the deployment (`exportSigning`); a deployment without one answers `404 signing-not-configured`. It is the same envelope as the audit-bundle and provenance exports, so one verifier reads all three. Redaction happens when evidence is generated, not at the export boundary — records are stored already redacted.',
   audit:
     'PDP decision audit stream (list). Every route-level authz `check()` emits one `AuditEvent` (kind `authz-decision`) via the `AuditEventBinding`; this route pages through them, tenant-scoped, with `?actorSubject=` / `?onBehalfOf=` / `?action=` / `?resource=` / `?outcome=` / `?runId=` / `?from=` / `?to=` filters. Admin@tenant only. This view is a filtered projection of the tenant audit events.',
   orgs: 'Multi-tenant hierarchy — Org CRUD (list, create, get, patch, delete). Optional structural subdivision within a tenant; small tenants ignore Orgs entirely. Caller-plugged via `OrgBinding` from `@kindgi/platform`.',
@@ -111,6 +113,8 @@ const TAG_DESCRIPTIONS: Readonly<Record<string, string>> = {
   tenant:
     'Sovereignty boundary readback + tenant-scoped config (get tenant; list + upsert entries routed to the env / secrets bindings). There is no `/v1/tenants` collection — the caller\'s tenant is implicit from the bearer token. `PATCH /config` routes writes to `SecretBinding` when `sensitive: true` OR `kind: "secret"`; else to `EnvBinding`. `GET /config` merges both bindings at tenant scope; secret values are ALWAYS redacted here. The `/config` sub-routes mount when at least one of `envBinding` / `secretsBinding` is wired. Prefer `/v1/env/*` + `/v1/secrets/*` for new callers.',
   env: 'Non-sensitive per-env values (`/v1/env/*`). Every route requires `envName` + `scopeKind` (+ `scopeId` for org / project); `value` is present on every read path (env is non-sensitive by definition). Writes require the `env:write` capability. Caller-plugged via `EnvBinding` (`@kindgi/env-inmemory` is an in-memory implementation for development and tests).',
+  schedules:
+    "Run an agent or a flow on a schedule: a cron expression in a timezone. Each occurrence is one fire, which starts one run as the schedule's owner (re-checked at every fire), through the same path as `POST /v1/runs`; a run a schedule started names it (`Run.trigger`). After a gap, `catchUp` runs once for the latest missed occurrence (or skips them), never once per missed one; `overlap` skips an occurrence while the previous run is still going. `GET …/fires` is the schedule's history; `run-now` fires it outside the schedule. Mounted when the deployment fires schedules.",
   'webhook-endpoints':
     'Outbound webhooks: endpoints the platform sends signed events to (`run.finished` when a top-level run completes, fails or is cancelled), their delivery log, redelivery and a test event. Signed in the Standard Webhooks format with a secret the endpoint references by name (`secretRef`); delivered at least once, so receivers deduplicate on `webhook-id`. Event bodies are under `webhooks`. Not to be confused with `/v1/webhooks`, which are inbound triggers. Caller-plugged via `WebhookEndpointBinding`.',
   secrets:
@@ -212,6 +216,11 @@ function buildOutboundWebhooks(): Record<string, unknown> {
       'A top-level run completed, failed or was cancelled',
       'RunFinishedEvent',
     ),
+    'improvement-pass.finished': event(
+      'improvement-pass.finished',
+      'An improvement pass completed, failed or was cancelled',
+      'ImprovementPassFinishedEvent',
+    ),
     'webhook.test': event(
       'webhook.test',
       'A test event sent on request (`POST /v1/webhook-endpoints/{endpointId}/test`)',