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

package/src/routes/provenance.ts

@@ -2,15 +2,18 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
+import type { Context, Next } from 'hono';
 
 import type { ConversationBinding } from '@kindgi/agents';
-import { serializePublicKeyPem, signEd25519 } from '@kindgi/crypto';
-import type { SigningKeyBinding } from '@kindgi/crypto';
-import { canonicalize } from '@kindgi/schema';
-import type { ConversationId, RunId, SigningKeyId, TenantId, Timestamp } from '@kindgi/types';
+import type { AuditEventBinding } from '@kindgi/audit-events';
+import { ref } from '@kindgi/authz';
+import type { ExportSigningBinding } from '@kindgi/crypto';
+import type { RunBinding } from '@kindgi/runtime';
+import type { ConversationId, RunId, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
 
+import type { Authorizer } from '../middleware/authorize.js';
 import type {
   CallUsageByCallId,
   ProvenanceBinding,
@@ -18,9 +21,18 @@ import type {
   ProvenanceListCursor,
   ProvenanceRecordSummary,
 } from '../provenance-binding.js';
+import {
+  exportActor,
+  parseSigningKeyId,
+  readExportBody,
+  signExport,
+  signExportFailure,
+  signingNotConfigured,
+} from '../signed-export.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
 import { parseListScope } from './scope-params.js';
+import { UUID_RE } from './uuid-param.js';
 
 /**
  * Provenance resource routes.
@@ -41,25 +53,56 @@ import { parseListScope } from './scope-params.js';
  * server round trip.
  */
 export interface ProvenanceRouterOptions {
-  readonly signingKey?: SigningKeyBinding;
+  /** Signs provenance exports. Absent: `POST /:runId/export` answers `404 signing-not-configured`. */
+  readonly exportSigning?: ExportSigningBinding;
+  /** Records each signed export (`export-signed`). */
+  readonly auditEvents?: AuditEventBinding;
   /**
    * Conversation binding used by the signed-export path to read
    * conversation transcripts (`readMessages`) alongside provenance
    * DAGs. Absent = the export omits messages (empty array).
    */
   readonly conversationBinding?: ConversationBinding;
+  /** Where a run's project is read, for the per-run checks (T243 A). */
+  readonly runBinding?: RunBinding;
 }
 
 /** Bundle schema version — bump when the wire shape of `bundle.body` changes. */
 /** 1.1.0 adds `callUsage`: the model calls' usage from the cost ledger, when the run has any. */
-const BUNDLE_SCHEMA_VERSION = '1.1.0';
+/** 1.2.0: `exportedAt` is in the signed body (was the envelope's only). */
+const BUNDLE_SCHEMA_VERSION = '1.2.0';
 
 export function provenanceRouter(
   binding: ProvenanceBinding,
   options: ProvenanceRouterOptions = {},
+  /**
+   * With one (T243 A): a run's provenance (and its export) needs `read`
+   * on the run's project; the list holds only records whose project the
+   * caller may read (the tenant, for one with no project).
+   */
+  authorizer?: Authorizer,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
-  const signingKey = options.signingKey;
+  if (authorizer !== undefined) {
+    // A run that isn't there is the handler's 404 (`read` on the tenant).
+    // An id that isn't a run id is never looked up (its uuid cast would
+    // fail the query as a 500).
+    const onRunProject = async (c: Context<AppEnv>, next: Next) => {
+      const tenantId = c.get('tenantId') as TenantId;
+      const runId = c.req.param('runId') ?? '';
+      const run = UUID_RE.test(runId)
+        ? await options.runBinding?.getRun(tenantId, runId as RunId)
+        : undefined;
+      const at =
+        run === undefined || run === null
+          ? ref('tenant', tenantId as unknown as string)
+          : ref('project', run.projectId as unknown as string);
+      return authorizer.authorize('read', () => at)(c, next);
+    };
+    r.use('/:runId', async (c, next) => (c.req.method === 'GET' ? onRunProject(c, next) : next()));
+    r.use('/:runId/export', onRunProject);
+  }
+  const exportSigning = options.exportSigning;
 
   // ---------- GET / (list metadata, cursor-paginated) ----------
   r.get('/', async (c) => {
@@ -125,8 +168,16 @@ export function provenanceRouter(
     }
     const { records, nextCursor } = result.value;
     const hasMore = nextCursor !== undefined;
+    const visible =
+      authorizer === undefined
+        ? records
+        : await authorizer.filterByCan(c, 'read', records, (rec) =>
+            rec.projectId !== undefined
+              ? ref('project', rec.projectId as unknown as string)
+              : ref('tenant', tenantId as unknown as string),
+          );
     return c.json({
-      data: records.map(serializeRecordMetadata),
+      data: visible.map(serializeRecordMetadata),
       hasMore,
       ...(nextCursor !== undefined && {
         nextCursor: encodeCursor({ createdAt: nextCursor.createdAt, id: nextCursor.id }),
@@ -195,36 +246,10 @@ export function provenanceRouter(
     const tenantId = c.get('tenantId') as TenantId;
     const runId = c.req.param('runId') as RunId;
 
-    if (signingKey === undefined) {
-      c.status(statusFor('signing-not-configured') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'signing-not-configured',
-            message:
-              'This deployment does not have a `signingKey` binding mounted; signed provenance exports are unavailable.',
-          },
-          requestId,
-        ),
-      );
-    }
+    if (exportSigning === undefined) return signingNotConfigured(c, 'signed provenance exports');
 
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      c.status(statusFor('bad-input') as never);
-      return c.json(
-        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
-      );
-    }
-    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
-      c.status(statusFor('bad-input') as never);
-      return c.json(
-        toWireError({ code: 'bad-input', message: 'Request body must be an object' }, requestId),
-      );
-    }
-    const parsed = parseExportBody(body as Record<string, unknown>);
+    const read = await readExportBody(c);
+    const parsed = read.kind === 'ok' ? parseExportBody(read.value) : read;
     if (parsed.kind === 'err') {
       c.status(statusFor('bad-input') as never);
       return c.json(toWireError({ code: 'bad-input', message: parsed.message }, requestId));
@@ -282,94 +307,43 @@ export function provenanceRouter(
       }
     }
 
-    // 3. Look up the private key material.
-    const privateKey = signingKey.getPrivateKey(signingKeyId);
-    if (privateKey === null) {
-      c.status(statusFor('signing-key-not-found') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'signing-key-not-found',
-            message: `No signing key registered with id "${signingKeyId as unknown as string}"`,
-            signingKeyId: signingKeyId as unknown as string,
-          },
-          requestId,
-        ),
-      );
-    }
-    const publicKeyRaw = signingKey.getPublicKey(signingKeyId);
-    if (publicKeyRaw === null) {
-      // Contract: `getPublicKey` never returns null for a key that
-      // `getPrivateKey` resolved. Treat mismatch as a binding bug.
-      c.status(statusFor('signing-key-not-found') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'signing-key-not-found',
-            message: `Signing key "${signingKeyId as unknown as string}" resolved a private key but no public key`,
-            signingKeyId: signingKeyId as unknown as string,
-          },
-          requestId,
-        ),
-      );
-    }
-
-    // 4. Build the canonical bundle body. Bundle shape is v1.0.0 —
-    //    ordering here is irrelevant for signing (canonicalize sorts
-    //    keys) but declared explicitly for reviewer scanability.
-    const bundleBody = {
+    // 3. Sign the bundle body (and record the export).
+    const signed = await signExport({
+      signer: exportSigning,
+      kind: 'provenance',
       bundleSchemaVersion: BUNDLE_SCHEMA_VERSION,
-      provenanceId: provenance.id as unknown as string,
-      runId: provenance.runId as unknown as string,
-      tenantId: provenance.tenantId as unknown as string,
-      version: provenance.version,
-      createdAt: provenance.createdAt as unknown as string,
-      ...(provenance.flowRef !== undefined && {
-        flowRef: {
-          id: provenance.flowRef.id as unknown as string,
-          version: provenance.flowRef.version,
+      ...(signingKeyId !== undefined && { signingKeyId }),
+      body: {
+        provenanceId: provenance.id as unknown as string,
+        runId: provenance.runId as unknown as string,
+        tenantId: provenance.tenantId as unknown as string,
+        version: provenance.version,
+        createdAt: provenance.createdAt as unknown as string,
+        ...(provenance.flowRef !== undefined && {
+          flowRef: {
+            id: provenance.flowRef.id as unknown as string,
+            version: provenance.flowRef.version,
+          },
+        }),
+        dag: {
+          nodes: provenance.nodes,
+          edges: provenance.edges,
         },
-      }),
-      dag: {
-        nodes: provenance.nodes,
-        edges: provenance.edges,
+        ...(messages !== undefined && { messages }),
+        ...(callUsage.value !== undefined && { callUsage: callUsage.value }),
       },
-      ...(messages !== undefined && { messages }),
-      ...(callUsage.value !== undefined && { callUsage: callUsage.value }),
-    };
-    const canonicalBundleBytes = new TextEncoder().encode(canonicalize(bundleBody));
-
-    // 5. Sign the canonical bytes.
-    const signResult = signEd25519(privateKey, canonicalBundleBytes);
-    if (signResult.kind === 'err') {
-      c.status(statusFor('export-key-error') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'export-key-error',
-            message: `Failed to sign provenance bundle: ${signResult.error.message}`,
-          },
-          requestId,
-        ),
-      );
-    }
-
-    // 6. Emit the signed envelope. `bundle` is a base64 of the exact
-    //    bytes that were signed — verifiers decode + re-canonicalize
-    //    is unnecessary, they can verify against `atob(bundle)`
-    //    directly.
-    const exportedAt = new Date().toISOString() as Timestamp;
-    return c.json({
-      runId: runId as unknown as string,
-      bundle: Buffer.from(canonicalBundleBytes).toString('base64'),
-      bundleSchemaVersion: BUNDLE_SCHEMA_VERSION,
-      algorithm: 'ed25519' as const,
-      signingKeyId: signingKeyId as unknown as string,
-      signature: Buffer.from(signResult.value).toString('base64'),
-      publicKey: serializePublicKeyPem(publicKeyRaw),
-      canonicalization: 'sorted-key-json' as const,
-      exportedAt: exportedAt as unknown as string,
+      ...(options.auditEvents !== undefined && {
+        record: {
+          auditEvents: options.auditEvents,
+          tenantId,
+          runId: runId as unknown as string,
+          actor: exportActor(c),
+          subject: { runId: runId as unknown as string },
+        },
+      }),
     });
+    if (signed.kind === 'err') return signExportFailure(c, signed.error, 'export-key-error');
+    return c.json({ runId: runId as unknown as string, ...signed.value });
   });
 
   return r;
@@ -407,7 +381,7 @@ function serializeRecordMetadata(row: ProvenanceRecordSummary): RecordMetadata {
 }
 
 interface ValidatedExportBody {
-  readonly signingKeyId: SigningKeyId;
+  readonly signingKeyId: string | undefined;
   readonly includeMessages: boolean;
 }
 
@@ -416,10 +390,8 @@ type ParseResult<T> =
   | { readonly kind: 'err'; readonly message: string };
 
 function parseExportBody(body: Record<string, unknown>): ParseResult<ValidatedExportBody> {
-  const raw = body.signingKeyId;
-  if (typeof raw !== 'string' || raw.length === 0) {
-    return { kind: 'err', message: 'Field `signingKeyId` must be a non-empty string' };
-  }
+  const signingKeyId = parseSigningKeyId(body);
+  if (signingKeyId.kind === 'err') return signingKeyId;
   let includeMessages = false;
   if ('includeMessages' in body) {
     const im = body.includeMessages;
@@ -428,13 +400,7 @@ function parseExportBody(body: Record<string, unknown>): ParseResult<ValidatedEx
     }
     includeMessages = im;
   }
-  return {
-    kind: 'ok',
-    value: {
-      signingKeyId: raw as SigningKeyId,
-      includeMessages,
-    },
-  };
+  return { kind: 'ok', value: { signingKeyId: signingKeyId.value, includeMessages } };
 }
 
 /** The run's call usage, when the binding has a cost ledger and the run made calls. */

package/src/routes/providers.ts

@@ -5,19 +5,28 @@ import { Hono } from 'hono';
 
 import {
   type AdapterConfig,
+  type AdapterConfigProblem,
+  type AdapterFactoryRegistry,
   FEATURES,
   type Feature,
   type ModelInfo,
   type ProviderMetadata,
+  isModelThinking,
   validateProviderLabels,
 } from '@kindgi/capabilities';
 import type { Cursor, TenantId } from '@kindgi/types';
 
 import type { CapabilityDescriptor } from '../capability-binding.js';
 import { statusFor, toWireError } from '../errors.js';
-import type { ProviderRegistryBinding, ProviderSecretRef } from '../provider-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type {
+  ProviderRegistryBinding,
+  ProviderRuntimeEntry,
+  ProviderSecretRef,
+} from '../provider-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { tenantResourceAccess } from './tenant-access.js';
 
 /**
  * Providers resource routes — part of the admin control plane. Full
@@ -46,11 +55,20 @@ export type ProviderWriteHook = (params: {
   readonly kind: 'register' | 'unregister';
 }) => void | Promise<void>;
 
+/**
+ * `factories`: the deployment's in-process adapter factories. With them, a
+ * registration is checked against its adapter's `checkConfig` before it's
+ * stored, and `GET /:providerId/check` answers for a registered one.
+ * Without them, registration takes any flat `adapter_config`.
+ */
 export function providersRouter(
   binding: ProviderRegistryBinding,
   onWrite?: ProviderWriteHook,
+  factories?: AdapterFactoryRegistry,
+  authorizer?: Authorizer,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  r.use('*', tenantResourceAccess(authorizer));
 
   // ---------- GET / (list, cursor-paginated) ----------
   r.get('/', async (c) => {
@@ -151,12 +169,15 @@ export function providersRouter(
     //                                     runtime bridge),
     //     "adapter_config": { … }         (optional — the adapter's flat,
     //                                     non-secret connection settings)
+    //     "send_traceparent": boolean     (optional — send each call's
+    //                                     traceparent to the provider)
     //   }
     const bodyObj = body as {
       readonly metadata?: unknown;
       readonly adapter_id?: unknown;
       readonly secret_ref?: unknown;
       readonly adapter_config?: unknown;
+      readonly send_traceparent?: unknown;
     };
     if (bodyObj.metadata === undefined) {
       c.status(statusFor('bad-input') as never);
@@ -216,12 +237,38 @@ export function providersRouter(
       );
     }
 
+    // The registration's own fields first, then the adapter's check of what
+    // it'll be built from: refused now, naming the field, instead of skipped
+    // at the first model call. One answer lists them all.
+    const sendTraceparent = bodyObj.send_traceparent;
+    const adapterProblems = configProblems(factories, {
+      metadata: validation.value,
+      adapterId: bodyObj.adapter_id,
+      ...(secretRefResult.value !== undefined && { secretRef: secretRefResult.value }),
+      ...(adapterConfigResult.value !== undefined && { adapterConfig: adapterConfigResult.value }),
+    });
+    const problems = [...registrationProblems(bodyObj), ...(adapterProblems ?? [])];
+    if (problems.length > 0) {
+      c.status(statusFor('provider-config-invalid') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'provider-config-invalid',
+            message: refusalOf(validation.value.id, bodyObj.adapter_id, problems),
+            issues: problems,
+          },
+          requestId,
+        ),
+      );
+    }
+
     const outcome = await binding.register({
       tenantId,
       metadata: validation.value,
       adapterId: bodyObj.adapter_id,
       ...(secretRefResult.value !== undefined && { secretRef: secretRefResult.value }),
       ...(adapterConfigResult.value !== undefined && { adapterConfig: adapterConfigResult.value }),
+      ...(typeof sendTraceparent === 'boolean' && { sendTraceparent }),
     });
     if (outcome.kind === 'already-registered') {
       c.status(statusFor('provider-already-registered') as never);
@@ -264,6 +311,31 @@ export function providersRouter(
     return c.json({ providerId: outcome.providerId });
   });
 
+  // ---------- GET /:providerId/check ----------
+  r.get('/:providerId/check', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const providerId = c.req.param('providerId');
+    const entries = await binding.resolveForRuntime({ tenantId });
+    const entry = entries.find((e) => e.metadata.id === providerId);
+    if (entry === undefined) {
+      c.status(statusFor('provider-not-found') as never);
+      return c.json(
+        toWireError(
+          { code: 'provider-not-found', message: `Provider "${providerId}" not found`, providerId },
+          requestId,
+        ),
+      );
+    }
+    const problems = configProblems(factories, entry);
+    return c.json({
+      providerId,
+      adapterId: entry.adapterId,
+      checked: problems !== undefined,
+      issues: problems ?? [],
+    });
+  });
+
   // ---------- POST /:providerId/unregister ----------
   r.post('/:providerId/unregister', async (c) => {
     const requestId = c.get('requestId');
@@ -305,14 +377,15 @@ function serializeProvider(m: ProviderMetadata): Record<string, unknown> {
       name: model.name,
       contextWindow: model.contextWindow,
       features: model.features,
-      cost: {
-        promptUsdPer1kTokens: model.cost.promptUsdPer1kTokens,
-        completionUsdPer1kTokens: model.cost.completionUsdPer1kTokens,
-      },
+      // As stored: the base rates and any an adapter widens it with.
+      cost: { ...model.cost },
       ...(model.p95LatencyMs !== undefined && { p95LatencyMs: model.p95LatencyMs }),
       ...(model.maxOutputTokens !== undefined && { maxOutputTokens: model.maxOutputTokens }),
+      ...(model.sampling !== undefined && { sampling: model.sampling }),
+      ...(model.thinking !== undefined && { thinking: model.thinking }),
       ...(model.description !== undefined && { description: model.description }),
     })),
+    ...(m.defaultModel !== undefined && { defaultModel: m.defaultModel }),
     ...(m.attributes !== undefined && { attributes: m.attributes }),
     ...(m.description !== undefined && { description: m.description }),
     ...(m.capabilityKind !== undefined && { capabilityKind: m.capabilityKind }),
@@ -328,6 +401,9 @@ function serializeCapability(d: CapabilityDescriptor): Record<string, unknown> {
     description: d.description,
     ...(d.kind !== undefined && { kind: d.kind }),
     ...(d.paramsSchema !== undefined && { paramsSchema: d.paramsSchema }),
+    ...(d.providers !== undefined && {
+      providers: d.providers.map((p) => ({ providerId: p.providerId, models: [...p.models] })),
+    }),
   };
 }
 
@@ -436,10 +512,20 @@ function validateProviderMetadata(
   }
   const badLabels = validateProviderLabels(b.id, b.labels);
   if (badLabels !== undefined) return { kind: 'err', error: badLabels };
+  if (b.defaultModel !== undefined && !seenNames.has(b.defaultModel as string)) {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${b.id}" defaultModel must be one of its models (${[...seenNames].join(', ')}), got ${JSON.stringify(b.defaultModel)}`,
+        reason: 'unknown-default-model',
+      },
+    };
+  }
   const value: ProviderMetadata = {
     id: b.id,
     region: b.region,
     models: validatedModels,
+    ...(b.defaultModel !== undefined && { defaultModel: b.defaultModel as string }),
     ...(b.attributes !== undefined && { attributes: b.attributes as readonly string[] }),
     ...(b.description !== undefined && { description: b.description }),
     ...(b.capabilityKind !== undefined && { capabilityKind: b.capabilityKind as string }),
@@ -527,6 +613,16 @@ function validateModelInfo(
       },
     };
   }
+  const extraRates = costExtraRates(cost as unknown as Record<string, unknown>);
+  if (extraRates === undefined) {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${providerId}" model "${m.name}" cost table's other rates must be non-negative numbers, or objects of them (e.g. longContext: { thresholdTokens, promptUsdPer1kTokens, completionUsdPer1kTokens })`,
+        reason: 'invalid-cost',
+      },
+    };
+  }
   if (m.p95LatencyMs !== undefined) {
     if (typeof m.p95LatencyMs !== 'number' || m.p95LatencyMs < 0) {
       return {
@@ -553,6 +649,24 @@ function validateModelInfo(
       };
     }
   }
+  if (m.sampling !== undefined && typeof m.sampling !== 'boolean') {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${providerId}" model "${m.name}" sampling must be true or false`,
+        reason: 'invalid-sampling',
+      },
+    };
+  }
+  if (m.thinking !== undefined && !isModelThinking(m.thinking)) {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${providerId}" model "${m.name}" thinking must be { mode: 'adaptive' | 'always', lowest: <the vendor's setting> }`,
+        reason: 'invalid-thinking',
+      },
+    };
+  }
   if (m.description !== undefined && typeof m.description !== 'string') {
     return {
       kind: 'err',
@@ -567,21 +681,122 @@ function validateModelInfo(
     contextWindow: m.contextWindow,
     features: m.features as readonly Feature[],
     cost: {
+      ...extraRates,
       promptUsdPer1kTokens: cost.promptUsdPer1kTokens,
       completionUsdPer1kTokens: cost.completionUsdPer1kTokens,
-    },
+    } as ModelInfo['cost'],
     ...(m.p95LatencyMs !== undefined && { p95LatencyMs: m.p95LatencyMs }),
     ...(m.maxOutputTokens !== undefined && { maxOutputTokens: m.maxOutputTokens }),
+    ...(m.sampling !== undefined && { sampling: m.sampling }),
+    ...(m.thinking !== undefined && {
+      thinking: { mode: m.thinking.mode, lowest: m.thinking.lowest },
+    }),
     ...(m.description !== undefined && { description: m.description }),
   };
   return { kind: 'ok', value };
 }
 
+/**
+ * The rates a cost table carries beyond the two base ones: an adapter
+ * widens it with its own (Anthropic's prompt-cache multipliers, Gemini's
+ * cached-prompt share, a long-context tier), each a non-negative number
+ * or one level of an object of them. Returned as given, or `undefined`
+ * when one isn't, so a registration keeps what its adapter prices with.
+ */
+function costExtraRates(
+  cost: Readonly<Record<string, unknown>>,
+): Record<string, number | Record<string, number>> | undefined {
+  const isRate = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+  const out: Record<string, number | Record<string, number>> = {};
+  for (const [key, value] of Object.entries(cost)) {
+    if (key === 'promptUsdPer1kTokens' || key === 'completionUsdPer1kTokens') continue;
+    if (isRate(value)) {
+      out[key] = value;
+    } else if (
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      Object.keys(value).length > 0 &&
+      Object.values(value).every(isRate)
+    ) {
+      out[key] = { ...(value as Record<string, number>) };
+    } else {
+      return undefined;
+    }
+  }
+  return out;
+}
+
+/**
+ * What's wrong with a registration, by its adapter's own static check
+ * (`AdapterFactoryEntry.checkConfig`): no network, no secret read.
+ * `undefined` when there's nothing to check it with (no factories wired, or
+ * an adapter without a check). An adapter the deployment doesn't have is a
+ * problem: the runtime could never build the provider.
+ */
+function configProblems(
+  factories: AdapterFactoryRegistry | undefined,
+  registration: ProviderRuntimeEntry,
+): readonly AdapterConfigProblem[] | undefined {
+  if (factories === undefined) return undefined;
+  const entry = factories.get(registration.adapterId);
+  if (entry === undefined) {
+    return [
+      {
+        path: '/adapter_id',
+        message: `This runtime has no adapter "${registration.adapterId}", so it can't build provider "${registration.metadata.id}".`,
+      },
+    ];
+  }
+  return entry.checkConfig?.({
+    metadata: registration.metadata,
+    ...(registration.adapterConfig !== undefined && { config: registration.adapterConfig }),
+    hasSecretRef: registration.secretRef !== undefined,
+  });
+}
+
+/**
+ * What's wrong with the registration's own fields, before its adapter's:
+ * `send_traceparent`, when present, is a boolean. The runtime, not the
+ * adapter, reads it.
+ */
+export function registrationProblems(body: {
+  readonly send_traceparent?: unknown;
+}): readonly AdapterConfigProblem[] {
+  const value = body.send_traceparent;
+  return value === undefined || typeof value === 'boolean'
+    ? []
+    : [{ path: '/send_traceparent', message: 'send_traceparent must be true or false.' }];
+}
+
+/**
+ * The 422's message: one sentence naming the provider, its adapter and the
+ * first problem, with a count of the rest (`details.issues` lists each).
+ * A problem with the registration's own fields names the provider alone.
+ */
+function refusalOf(
+  providerId: string,
+  adapterId: string,
+  problems: readonly AdapterConfigProblem[],
+): string {
+  const [first, ...rest] = problems;
+  if (first === undefined) return `Provider "${providerId}" doesn't fit adapter ${adapterId}.`;
+  if (first.path === '/adapter_id') return first.message;
+  const more = rest.length > 0 ? ` (and ${rest.length} more)` : '';
+  const what = first.message.replace(/\.$/, '');
+  return REGISTRATION_PATHS.has(first.path)
+    ? `Provider "${providerId}": ${what}${more}.`
+    : `Provider "${providerId}" doesn't fit adapter ${adapterId}: ${what}${more}.`;
+}
+
+/** The paths `registrationProblems` reports: the registration's own fields, not its adapter's. */
+const REGISTRATION_PATHS: ReadonlySet<string> = new Set(['/send_traceparent']);
+
 /**
  * Parse the optional `adapter_config` on the register request body: a
  * flat object of string, number or boolean values. Credentials don't
- * belong here (they ride on `secret_ref`); the adapter validates its
- * own keys when it is instantiated.
+ * belong here (they ride on `secret_ref`); the adapter checks its own keys
+ * (`configProblems`).
  */
 function parseAdapterConfig(
   raw: unknown,