@7h3/protocol 0.1.2 → 0.5.0

package/src/mcpWrapper.ts

@@ -0,0 +1,206 @@
+import { createEnvelope, type ProtocolEnvelope } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import {
+  encodeEnvelope,
+  receiveEnvelope,
+  type ReceiveEnvelopeOptions,
+  type WireEnvelope,
+  type WireFormat,
+} from './protocolTransport'
+
+/**
+ * MCP hardening middleware.
+ *
+ * MCP messages are plain JSON-RPC 2.0 and, as shipped, carry no signature or
+ * replay protection. These wrappers put an AIP envelope around each message on
+ * the wire — signing, TTL-bounding, and replay-checking every request and
+ * response — while the underlying MCP handler still receives plain JSON-RPC.
+ * "Zero app changes": your handler signature does not change.
+ *
+ * The wrappers enforce four bindings beyond signature verification:
+ *   - recipient binding: the server only runs the handler when the envelope is
+ *     addressed to it (`recipient === selfAgentId`) — defeats cross-server relay.
+ *   - sender binding: the client only accepts responses from its expected peer
+ *     (`sender === peerAgentId`) — defeats response spoofing.
+ *   - correlation binding: the client only accepts a response whose
+ *     `correlationId` matches the request it sent — defeats response substitution.
+ *   - replay protection on by default (an `InMemoryReplayCache` if none supplied).
+ *
+ * Verification reuses the transport pipeline (`receiveEnvelope`), so it composes
+ * directly with a Redis-backed replay cache (`createRedisReplayStore`) and
+ * fleet-wide revocation (`withRevocationCheck`) via the `receive` options.
+ */
+
+export type JsonRpcId = string | number | null
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: JsonRpcId
+  method: string
+  params?: unknown
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: JsonRpcId
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+}
+
+export type McpJsonRpcHandler = (request: JsonRpcRequest) => JsonRpcResponse | Promise<JsonRpcResponse>
+
+export interface McpSecurityOptions {
+  /** This peer's agent id, used as the envelope `sender` and enforced as the inbound `recipient`. */
+  selfAgentId: string
+  /** The peer's agent id: set as the envelope `recipient` (client) and enforced as the response `sender`. */
+  peerAgentId?: string
+  /** Signs an unsigned envelope, e.g. `(e) => signEnvelopeHmac(e, secret, keyId)`. */
+  sign: (envelope: Omit<ProtocolEnvelope, 'signature'>) => Promise<ProtocolEnvelope>
+  /** Inbound verification options: signature material resolver, replay cache, clock skew, etc. */
+  receive?: ReceiveEnvelopeOptions
+  /** Wire format for the envelope on the wire. Default `compact`. */
+  wireFormat?: WireFormat
+  /** Envelope TTL in ms. Default 60_000. */
+  ttlMs?: number
+}
+
+export interface EncodedRequest {
+  raw: WireEnvelope
+  /** The envelope `messageId` generated for this request; bind the response's `correlationId` to it. */
+  messageId: string
+}
+
+export interface DecodeResponseOptions {
+  /** When set, require the response `correlationId` to equal this value (the request's messageId). */
+  expectCorrelationId?: string
+}
+
+function jsonRpcError(id: JsonRpcId, code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, error: { code, message } }
+}
+
+/** Verification options with signature required and a replay cache guaranteed (secure defaults). */
+function hardenedReceive(options: McpSecurityOptions, replayCache: ReceiveEnvelopeOptions['replayCache']): ReceiveEnvelopeOptions {
+  return { requireSignature: true, ...options.receive, replayCache }
+}
+
+/**
+ * Wraps an existing MCP JSON-RPC handler so every inbound message is verified
+ * (signature + replay + TTL + recipient binding) before the handler runs, and
+ * every response is signed. Returns a function over the AIP wire envelope.
+ */
+export function wrapMcpServer(handler: McpJsonRpcHandler, options: McpSecurityOptions): (raw: WireEnvelope) => Promise<WireEnvelope> {
+  const wireFormat = options.wireFormat ?? 'compact'
+  const ttlMs = options.ttlMs ?? 60_000
+  // Replay protection is on by default; supply a Redis-backed cache via options.receive for scale.
+  const replayCache = options.receive?.replayCache ?? new InMemoryReplayCache()
+  const receiveOptions = hardenedReceive(options, replayCache)
+
+  async function signAndEncode(envelope: Omit<ProtocolEnvelope, 'signature'>): Promise<WireEnvelope> {
+    return encodeEnvelope(await options.sign(envelope), wireFormat)
+  }
+
+  function reply(recipient: string | undefined, intent: 'RESULT' | 'ERROR', response: JsonRpcResponse, correlationId?: string) {
+    return signAndEncode(
+      createEnvelope({ sender: options.selfAgentId, recipient, intent, content: JSON.stringify(response), correlationId, ttlMs }),
+    )
+  }
+
+  return async (raw: WireEnvelope): Promise<WireEnvelope> => {
+    const received = await receiveEnvelope(raw, receiveOptions)
+    const senderHint = received.envelope?.header.sender
+    const correlationId = received.envelope?.header.messageId
+
+    if (!received.ok || !received.envelope) {
+      const reason = received.diagnostics.find((d) => d.level === 'error')?.message ?? 'AIP verification failed'
+      return reply(senderHint, 'ERROR', jsonRpcError(null, -32600, reason), correlationId)
+    }
+
+    // Recipient binding: refuse to act on an envelope not addressed to this agent.
+    if (received.envelope.header.recipient !== options.selfAgentId) {
+      return reply(senderHint, 'ERROR', jsonRpcError(null, -32600, 'Recipient mismatch: envelope not addressed to this agent'), correlationId)
+    }
+
+    let request: JsonRpcRequest
+    try {
+      request = JSON.parse(received.envelope.body.content) as JsonRpcRequest
+    } catch {
+      return reply(senderHint, 'ERROR', jsonRpcError(null, -32700, 'Parse error: envelope body is not JSON-RPC'), correlationId)
+    }
+
+    let response: JsonRpcResponse
+    try {
+      response = await handler(request)
+    } catch (error) {
+      response = jsonRpcError(request.id ?? null, -32603, error instanceof Error ? error.message : 'Internal error')
+    }
+    return reply(received.envelope.header.sender, 'RESULT', response, correlationId)
+  }
+}
+
+export interface McpClientCodec {
+  encodeRequest(request: JsonRpcRequest): Promise<EncodedRequest>
+  decodeResponse(raw: WireEnvelope, options?: DecodeResponseOptions): Promise<JsonRpcResponse>
+}
+
+/** Signs outbound requests and verifies inbound responses (with sender + correlation binding). */
+export function createMcpClientCodec(options: McpSecurityOptions): McpClientCodec {
+  const wireFormat = options.wireFormat ?? 'compact'
+  const ttlMs = options.ttlMs ?? 60_000
+  const replayCache = options.receive?.replayCache ?? new InMemoryReplayCache()
+  const receiveOptions = hardenedReceive(options, replayCache)
+
+  return {
+    async encodeRequest(request: JsonRpcRequest): Promise<EncodedRequest> {
+      const envelope = createEnvelope({
+        sender: options.selfAgentId,
+        recipient: options.peerAgentId,
+        intent: 'TASK',
+        content: JSON.stringify(request),
+        ttlMs,
+      })
+      return { raw: encodeEnvelope(await options.sign(envelope), wireFormat), messageId: envelope.header.messageId }
+    },
+
+    async decodeResponse(raw: WireEnvelope, decodeOptions: DecodeResponseOptions = {}): Promise<JsonRpcResponse> {
+      const received = await receiveEnvelope(raw, receiveOptions)
+      if (!received.ok || !received.envelope) {
+        const reason = received.diagnostics.find((d) => d.level === 'error')?.message ?? 'unknown'
+        throw new Error(`AIP response verification failed: ${reason}`)
+      }
+
+      // Sender binding: the response must come from the expected peer.
+      if (!options.peerAgentId) {
+        throw new Error('createMcpClientCodec requires peerAgentId to bind the response sender')
+      }
+      if (received.envelope.header.sender !== options.peerAgentId) {
+        throw new Error(`AIP response sender '${received.envelope.header.sender}' is not the expected peer '${options.peerAgentId}'`)
+      }
+
+      // Correlation binding: the response must answer the request we sent.
+      if (decodeOptions.expectCorrelationId !== undefined && received.envelope.body.correlationId !== decodeOptions.expectCorrelationId) {
+        throw new Error(
+          `AIP response correlationId '${received.envelope.body.correlationId ?? ''}' does not match request '${decodeOptions.expectCorrelationId}'`,
+        )
+      }
+
+      return JSON.parse(received.envelope.body.content) as JsonRpcResponse
+    },
+  }
+}
+
+/**
+ * Wraps a transport send function (`stdio`, HTTP, ...) so callers issue and
+ * receive plain JSON-RPC while AIP signing, verification, and request/response
+ * correlation happen on the wire.
+ */
+export function wrapMcpClient(
+  send: (raw: WireEnvelope) => Promise<WireEnvelope>,
+  options: McpSecurityOptions,
+): (request: JsonRpcRequest) => Promise<JsonRpcResponse> {
+  const codec = createMcpClientCodec(options)
+  return async (request: JsonRpcRequest): Promise<JsonRpcResponse> => {
+    const { raw, messageId } = await codec.encodeRequest(request)
+    return codec.decodeResponse(await send(raw), { expectCorrelationId: messageId })
+  }
+}

package/src/otel.ts

@@ -0,0 +1,136 @@
+/**
+ * otel.ts — Optional OpenTelemetry integration for 7h3 Protocol
+ *
+ * Pass your @opentelemetry/api Tracer provider via setOtelProvider.
+ * No hard dependency — works with any OTel-compatible SDK or without any OTel at all.
+ *
+ * Duck-typed interfaces: any object matching the shape will work, including
+ * the real @opentelemetry/api TracerProvider.
+ *
+ * Usage:
+ *   import { setOtelProvider } from '@7h3/protocol/otel'
+ *   import { trace } from '@opentelemetry/api'
+ *
+ *   setOtelProvider(trace.getTracerProvider())
+ *
+ * Without OTel configured, withVerificationSpan and withAuditSpan call fn(null)
+ * with zero overhead.
+ */
+
+// ─── Duck-typed OTel interfaces ───────────────────────────────────────────────
+
+/**
+ * A minimal OTel-compatible span interface.
+ * Compatible with @opentelemetry/api Span.
+ */
+export interface OtelSpan {
+  setAttribute(key: string, value: string | number | boolean): void
+  end(): void
+  recordException(error: Error): void
+}
+
+/**
+ * A minimal OTel-compatible tracer interface.
+ * Compatible with @opentelemetry/api Tracer.
+ */
+export interface OtelTracer {
+  startSpan(name: string, attrs?: Record<string, string | number>): OtelSpan
+}
+
+/**
+ * A minimal OTel-compatible provider interface.
+ * Compatible with @opentelemetry/api TracerProvider.
+ */
+export interface OtelProvider {
+  getTracer(name: string): OtelTracer
+}
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+let _provider: OtelProvider | null = null
+
+// ─── Provider management ──────────────────────────────────────────────────────
+
+/**
+ * Register an OTel provider. Call once at application startup.
+ * Subsequent calls replace the previous provider.
+ */
+export function setOtelProvider(provider: OtelProvider): void {
+  _provider = provider
+}
+
+/**
+ * Returns the active OTel tracer for '7h3/protocol', or null if no provider
+ * has been registered.
+ */
+export function getOtelTracer(): OtelTracer | null {
+  if (_provider === null) return null
+  try {
+    return _provider.getTracer('7h3/protocol')
+  } catch {
+    return null
+  }
+}
+
+// ─── Span helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Creates a span named '7h3.verify' if OTel is configured, calls fn(span),
+ * records any exception, and ends the span on completion.
+ *
+ * If no OTel provider is registered, calls fn(null) directly with zero overhead.
+ */
+export async function withVerificationSpan<T>(
+  fn: (span: OtelSpan | null) => Promise<T>,
+  attrs?: Record<string, string | number>,
+): Promise<T> {
+  const tracer = getOtelTracer()
+  if (tracer === null) {
+    return fn(null)
+  }
+
+  const span = tracer.startSpan('7h3.verify', attrs)
+  try {
+    const result = await fn(span)
+    return result
+  } catch (err) {
+    if (err instanceof Error) {
+      span.recordException(err)
+    } else {
+      span.recordException(new Error(String(err)))
+    }
+    throw err
+  } finally {
+    span.end()
+  }
+}
+
+/**
+ * Creates a span named '7h3.audit.write' if OTel is configured, calls fn(span),
+ * records any exception, and ends the span on completion.
+ *
+ * If no OTel provider is registered, calls fn(null) directly with zero overhead.
+ */
+export async function withAuditSpan<T>(
+  fn: (span: OtelSpan | null) => Promise<T>,
+): Promise<T> {
+  const tracer = getOtelTracer()
+  if (tracer === null) {
+    return fn(null)
+  }
+
+  const span = tracer.startSpan('7h3.audit.write')
+  try {
+    const result = await fn(span)
+    return result
+  } catch (err) {
+    if (err instanceof Error) {
+      span.recordException(err)
+    } else {
+      span.recordException(new Error(String(err)))
+    }
+    throw err
+  } finally {
+    span.end()
+  }
+}

package/src/policyEnforcer.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest'
+import { bootstrapRuntimePolicyEnforcer, createPolicyEnforcer, isRuntimeMode } from './policyEnforcer'
+import type { RuntimePolicy } from './runtimePolicy'
+
+const policy: RuntimePolicy = {
+  version: '1.0',
+  name: 'gluv-runtime-policy',
+  status: 'active',
+  slo_defaults: {
+    drop_pct_max: 0.1,
+    p99_ms_max: 20,
+  },
+  tuning: {
+    batch_size: {
+      low_traffic: [4, 8],
+      medium_traffic: [8, 32],
+      high_traffic: [32, 64],
+    },
+    inflight_cap: {
+      low_traffic: [16, 64],
+      medium_traffic: [64, 256],
+      high_traffic: [256, 1024],
+    },
+    retry_backoff_ms: {
+      low_traffic: [1, 2],
+      medium_traffic: [2, 8],
+      high_traffic: [4, 16],
+    },
+    max_retry_attempts: 3,
+    retriable_status_codes: [503],
+  },
+}
+
+describe('policy enforcer', () => {
+  it('selects binary batch for high concurrency', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(enforcer.selectMode({ concurrency: 100 })).toBe('http-binary-batch')
+  })
+
+  it('selects ws-batch for latency-sensitive low concurrency', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(enforcer.selectMode({ concurrency: 10, latencySensitive: true })).toBe('ws-batch')
+  })
+
+  it('returns tuning ranges and remediation actions', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    const decision = enforcer.tune({
+      trafficClass: 'high',
+      dropPct: 1,
+      p99Ms: 30,
+    })
+    expect(decision.batchSizeRange).toEqual([32, 64])
+    expect(decision.inflightCapRange).toEqual([256, 1024])
+    expect(decision.retryBackoffMsRange).toEqual([4, 16])
+    expect(decision.actions.length).toBeGreaterThan(0)
+  })
+
+  it('retries only retriable status and under attempt cap', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(enforcer.shouldRetry({ error: new Error('http status 503: overloaded'), attempt: 1 })).toBe(true)
+    expect(enforcer.shouldRetry({ error: new Error('http status 400: bad request'), attempt: 1 })).toBe(false)
+    expect(enforcer.shouldRetry({ error: new Error('http status 503: overloaded'), attempt: 3 })).toBe(false)
+  })
+
+  it('asserts invariants', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(() =>
+      enforcer.assertInvariant({
+        signatureVerification: true,
+        canonicalization: true,
+        replayDefense: true,
+        ttlClockSkewEnforcement: true,
+      }),
+    ).not.toThrow()
+    expect(() =>
+      enforcer.assertInvariant({
+        signatureVerification: false,
+        canonicalization: true,
+        replayDefense: true,
+        ttlClockSkewEnforcement: true,
+      }),
+    ).toThrow(/Invariant violation/i)
+  })
+
+  it('checks runtime mode literals', () => {
+    expect(isRuntimeMode('http-binary-batch')).toBe(true)
+    expect(isRuntimeMode('invalid-mode')).toBe(false)
+  })
+
+  it('bootstraps policy + enforcer in one call', async () => {
+    const bootstrapped = await bootstrapRuntimePolicyEnforcer({
+      path: '/virtual/AI_RUNTIME_POLICY.json',
+      readTextFile: async () => JSON.stringify(policy),
+    })
+
+    expect(bootstrapped.policy.name).toBe('gluv-runtime-policy')
+    expect(bootstrapped.enforcer.selectMode({ concurrency: 100 })).toBe('http-binary-batch')
+  })
+})

package/src/policyEnforcer.ts

@@ -0,0 +1,169 @@
+import { loadRuntimePolicy, type LoadRuntimePolicyOptions, type RuntimePolicy } from './runtimePolicy'
+
+export type RuntimeMode =
+  | 'http'
+  | 'ws'
+  | 'http-binary'
+  | 'http-batch'
+  | 'http-binary-batch'
+  | 'ws-batch'
+  | 'ws-binary'
+  | 'ws-binary-batch'
+
+export interface ModeSelectionInput {
+  concurrency: number
+  latencySensitive?: boolean
+  compatibilityFirst?: boolean
+}
+
+export interface TuningInput {
+  trafficClass: 'low' | 'medium' | 'high'
+  p99Ms?: number
+  dropPct?: number
+}
+
+export interface TuningDecision {
+  batchSizeRange: [number, number]
+  inflightCapRange: [number, number]
+  retryBackoffMsRange: [number, number]
+  actions: string[]
+}
+
+export interface RetryInput {
+  error: unknown
+  attempt: number
+}
+
+export interface InvariantConfig {
+  signatureVerification: boolean
+  canonicalization: boolean
+  replayDefense: boolean
+  ttlClockSkewEnforcement: boolean
+}
+
+function asNumberPair(value: unknown, label: string): [number, number] {
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new Error(`Invalid policy tuning range '${label}': expected [min,max]`)
+  }
+  const min = Number(value[0])
+  const max = Number(value[1])
+  if (!Number.isFinite(min) || !Number.isFinite(max) || min <= 0 || max < min) {
+    throw new Error(`Invalid policy tuning range '${label}': expected positive ascending numbers`)
+  }
+  return [Math.floor(min), Math.floor(max)]
+}
+
+function includeHttpLiteral(mode: string): mode is RuntimeMode {
+  return (
+    mode === 'http' ||
+    mode === 'ws' ||
+    mode === 'http-binary' ||
+    mode === 'http-batch' ||
+    mode === 'http-binary-batch' ||
+    mode === 'ws-batch' ||
+    mode === 'ws-binary' ||
+    mode === 'ws-binary-batch'
+  )
+}
+
+export function createPolicyEnforcer(policy: RuntimePolicy) {
+  const dropPctMax = Number((policy.slo_defaults ?? {}).drop_pct_max ?? 0.1)
+  const p99MsMax = Number((policy.slo_defaults ?? {}).p99_ms_max ?? 20)
+  const maxRetryAttempts = Number((policy.tuning ?? {}).max_retry_attempts ?? 3)
+  const retriableStatusCodes = Array.isArray((policy.tuning ?? {}).retriable_status_codes)
+    ? ((policy.tuning ?? {}).retriable_status_codes as unknown[])
+        .map((value) => Number(value))
+        .filter((value) => Number.isFinite(value))
+    : [503]
+
+  const tuning = policy.tuning ?? {}
+  const batchSize = tuning.batch_size as Record<string, unknown>
+  const inflightCap = tuning.inflight_cap as Record<string, unknown>
+  const retryBackoff = tuning.retry_backoff_ms as Record<string, unknown>
+
+  const getRanges = (trafficClass: 'low' | 'medium' | 'high') => ({
+    batchSizeRange: asNumberPair(batchSize?.[`${trafficClass}_traffic`], `batch_size.${trafficClass}_traffic`),
+    inflightCapRange: asNumberPair(inflightCap?.[`${trafficClass}_traffic`], `inflight_cap.${trafficClass}_traffic`),
+    retryBackoffMsRange: asNumberPair(retryBackoff?.[`${trafficClass}_traffic`], `retry_backoff_ms.${trafficClass}_traffic`),
+  })
+
+  function selectMode(input: ModeSelectionInput): RuntimeMode {
+    if (input.concurrency >= 100) return 'http-binary-batch'
+    if (input.latencySensitive) return 'ws-batch'
+    if (input.compatibilityFirst) return 'http'
+    return 'ws-batch'
+  }
+
+  function tune(input: TuningInput): TuningDecision {
+    const ranges = getRanges(input.trafficClass)
+    const actions: string[] = []
+
+    if (typeof input.dropPct === 'number' && input.dropPct > dropPctMax) {
+      actions.push('reduce inflight cap')
+      actions.push('reduce batch size')
+      actions.push('increase retry backoff')
+      actions.push('switch to binary-batch mode')
+    }
+    if (typeof input.p99Ms === 'number' && input.p99Ms > p99MsMax) {
+      actions.push('reduce batch size')
+      actions.push('reduce inflight cap')
+      actions.push('re-run adaptive benchmark')
+    }
+
+    return {
+      ...ranges,
+      actions,
+    }
+  }
+
+  function shouldRetry(input: RetryInput): boolean {
+    if (input.attempt >= maxRetryAttempts) return false
+    const message = input.error instanceof Error ? input.error.message : String(input.error)
+    const statusFromMessage = /http status\s+(\d+)/i.exec(message)
+    const statusCode = statusFromMessage ? Number(statusFromMessage[1]) : NaN
+    return Number.isFinite(statusCode) && retriableStatusCodes.includes(statusCode)
+  }
+
+  function assertInvariant(config: InvariantConfig): void {
+    const failures: string[] = []
+    if (!config.signatureVerification) failures.push('signatureVerification=false')
+    if (!config.canonicalization) failures.push('canonicalization=false')
+    if (!config.replayDefense) failures.push('replayDefense=false')
+    if (!config.ttlClockSkewEnforcement) failures.push('ttlClockSkewEnforcement=false')
+    if (failures.length > 0) {
+      throw new Error(`Invariant violation: ${failures.join(', ')}`)
+    }
+  }
+
+  return {
+    selectMode,
+    tune,
+    shouldRetry,
+    assertInvariant,
+    metadata: {
+      policyName: policy.name,
+      policyVersion: policy.version,
+      policyStatus: policy.status,
+      enforcedSlo: {
+        dropPctMax,
+        p99MsMax,
+      },
+    },
+  }
+}
+
+export type PolicyEnforcer = ReturnType<typeof createPolicyEnforcer>
+
+export type BootstrapRuntimePolicyEnforcerOptions = LoadRuntimePolicyOptions
+
+export async function bootstrapRuntimePolicyEnforcer(
+  options: BootstrapRuntimePolicyEnforcerOptions = {},
+): Promise<{ policy: RuntimePolicy; enforcer: PolicyEnforcer }> {
+  const policy = await loadRuntimePolicy(options)
+  const enforcer = createPolicyEnforcer(policy)
+  return { policy, enforcer }
+}
+
+export function isRuntimeMode(value: string): value is RuntimeMode {
+  return includeHttpLiteral(value)
+}

package/src/policyTelemetryFeedback.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { recommendPolicyAdjustments } from './policyTelemetryFeedback'
+
+describe('policy telemetry feedback', () => {
+  it('returns critical recommendation for severe drop/latency', () => {
+    const rec = recommendPolicyAdjustments({
+      mode: 'http',
+      p99Ms: 120,
+      dropPct: 5,
+      concurrency: 200,
+    })
+    expect(rec.severity).toBe('critical')
+    expect(rec.actions.length).toBeGreaterThan(0)
+  })
+
+  it('returns normal when metrics are healthy', () => {
+    const rec = recommendPolicyAdjustments({
+      mode: 'http-binary-batch',
+      p99Ms: 8,
+      dropPct: 0,
+      concurrency: 100,
+    })
+    expect(rec.severity).toBe('normal')
+  })
+})

package/src/policyTelemetryFeedback.ts

@@ -0,0 +1,38 @@
+export interface TelemetryFeedbackInput {
+  mode: string
+  p99Ms: number
+  dropPct: number
+  concurrency: number
+}
+
+export interface TelemetryFeedbackRecommendation {
+  severity: 'normal' | 'warn' | 'critical'
+  actions: string[]
+}
+
+export function recommendPolicyAdjustments(input: TelemetryFeedbackInput): TelemetryFeedbackRecommendation {
+  const actions: string[] = []
+  let severity: TelemetryFeedbackRecommendation['severity'] = 'normal'
+
+  if (input.dropPct > 0.1) {
+    actions.push('reduce inflight cap')
+    actions.push('reduce batch size')
+    actions.push('increase retry backoff')
+    if (input.mode === 'http' && input.concurrency >= 100) {
+      actions.push('switch to http-binary-batch')
+    }
+    severity = input.dropPct > 2 ? 'critical' : 'warn'
+  }
+
+  if (input.p99Ms > 20) {
+    actions.push('reduce batch size')
+    actions.push('run adaptive benchmark and re-baseline')
+    if (severity === 'normal') severity = 'warn'
+    if (input.p99Ms > 100) severity = 'critical'
+  }
+
+  return {
+    severity,
+    actions,
+  }
+}