@7h3/protocol 0.4.0 → 0.5.1

package/src/policyEnforcer.ts

@@ -1,169 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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,
-  }
-}

package/src/protocol.bench.ts

@@ -1,37 +0,0 @@
-import { bench, describe } from 'vitest'
-import { canonicalizeEnvelope, createEnvelope, signEnvelopeHmac, verifyEnvelopeHmac } from './protocol'
-import { decodeEnvelope, encodeEnvelope } from './protocolTransport'
-
-const unsigned = createEnvelope({
-  sender: 'agent.alpha',
-  recipient: 'agent.beta',
-  intent: 'TASK',
-  content: 'route-optimize:alpha-beta',
-  capability: 'task.plan',
-  correlationId: 'corr-1',
-  messageId: 'bench-1',
-  nonce: 'bench-nonce',
-  nowMs: 1_000,
-  ttlMs: 120_000,
-})
-
-describe('protocol throughput', () => {
-  bench('canonicalize envelope', () => {
-    canonicalizeEnvelope(unsigned)
-  })
-
-  bench('encode/decode envelope json', () => {
-    const encoded = encodeEnvelope({ ...unsigned })
-    decodeEnvelope(encoded)
-  })
-
-  bench('encode/decode envelope compact', () => {
-    const encoded = encodeEnvelope({ ...unsigned }, 'compact')
-    decodeEnvelope(encoded)
-  })
-
-  bench('sign + verify envelope', async () => {
-    const signed = await signEnvelopeHmac(unsigned, 'bench-secret', 'bench-k1')
-    await verifyEnvelopeHmac(signed, 'bench-secret')
-  })
-})

package/src/protocol.test.ts

@@ -1,155 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  canonicalizeEnvelope,
-  createEnvelope,
-  generateEd25519KeypairBase64Url,
-  signCanonicalPayloadHmac,
-  signEnvelopeEd25519,
-  signEnvelopeHmac,
-  verifyCanonicalPayloadEd25519,
-  validateEnvelope,
-  verifyCanonicalPayloadHmac,
-  verifyEnvelopeEd25519,
-  verifyEnvelopeHmac,
-} from './protocol'
-
-describe('GLUV AIP protocol', () => {
-  it('uses stable canonical field order', () => {
-    const envelope = createEnvelope({
-      sender: 'agent.alpha',
-      recipient: 'agent.beta',
-      intent: 'TASK',
-      content: 'compute route',
-      capability: 'task.plan',
-      correlationId: 'c-1',
-      messageId: 'm0',
-      nonce: 'n0',
-      nowMs: 500,
-      ttlMs: 10_000,
-    })
-
-    expect(canonicalizeEnvelope(envelope)).toBe(
-      '{"body":{"capability":"task.plan","content":"compute route","correlationId":"c-1","intent":"TASK"},"header":{"messageId":"m0","nonce":"n0","recipient":"agent.beta","sender":"agent.alpha","timestampMs":500,"ttlMs":10000,"version":"7h3/0.1"}}',
-    )
-  })
-
-  it('canonicalizes envelopes deterministically', () => {
-    const envelope = createEnvelope({
-      sender: 'agent.alpha',
-      recipient: 'agent.beta',
-      intent: 'TASK',
-      content: 'compute route',
-      messageId: 'm1',
-      nonce: 'n1',
-      nowMs: 1000,
-      ttlMs: 10000,
-    })
-
-    const c1 = canonicalizeEnvelope(envelope)
-    const c2 = canonicalizeEnvelope({ header: envelope.header, body: envelope.body })
-    expect(c1).toBe(c2)
-  })
-
-  it('signs and verifies with HMAC', async () => {
-    const unsigned = createEnvelope({
-      sender: 'agent.alpha',
-      intent: 'PING',
-      content: 'hello',
-      messageId: 'm2',
-      nonce: 'n2',
-      nowMs: 2000,
-      ttlMs: 10000,
-    })
-
-    const signed = await signEnvelopeHmac(unsigned, 'secret-key', 'dev-1')
-    const ok = await verifyEnvelopeHmac(signed, 'secret-key')
-    expect(ok).toBe(true)
-
-    const tampered = {
-      ...signed,
-      body: {
-        ...signed.body,
-        content: 'tampered',
-      },
-    }
-    const bad = await verifyEnvelopeHmac(tampered, 'secret-key')
-    expect(bad).toBe(false)
-  })
-
-  it('signs and verifies canonical payload directly', async () => {
-    const unsigned = createEnvelope({
-      sender: 'agent.alpha',
-      intent: 'PING',
-      content: 'hello',
-      messageId: 'm2b',
-      nonce: 'n2b',
-      nowMs: 2000,
-      ttlMs: 10000,
-    })
-
-    const payload = canonicalizeEnvelope(unsigned)
-    const sig = await signCanonicalPayloadHmac(payload, 'secret-key')
-    expect(await verifyCanonicalPayloadHmac(payload, sig, 'secret-key')).toBe(true)
-    expect(await verifyCanonicalPayloadHmac(`${payload}x`, sig, 'secret-key')).toBe(false)
-  })
-
-  it('signs and verifies with Ed25519', async () => {
-    const keys = await generateEd25519KeypairBase64Url()
-    const unsigned = createEnvelope({
-      sender: 'agent.alpha',
-      intent: 'TASK',
-      content: 'route:ed25519',
-      messageId: 'm-ed1',
-      nonce: 'n-ed1',
-      nowMs: 3000,
-      ttlMs: 10000,
-    })
-
-    const signed = await signEnvelopeEd25519(unsigned, keys.privateKey, 'ed-1')
-    const ok = await verifyEnvelopeEd25519(signed, keys.publicKey)
-    expect(ok).toBe(true)
-
-    const tampered = {
-      ...signed,
-      body: {
-        ...signed.body,
-        content: 'tampered',
-      },
-    }
-    const bad = await verifyEnvelopeEd25519(tampered, keys.publicKey)
-    expect(bad).toBe(false)
-  })
-
-  it('signs and verifies Ed25519 canonical payload directly', async () => {
-    const keys = await generateEd25519KeypairBase64Url()
-    const unsigned = createEnvelope({
-      sender: 'agent.alpha',
-      intent: 'PING',
-      content: 'hello-ed25519',
-      messageId: 'm-ed2',
-      nonce: 'n-ed2',
-      nowMs: 3100,
-      ttlMs: 10000,
-    })
-
-    const payload = canonicalizeEnvelope(unsigned)
-    const sig = await signEnvelopeEd25519(unsigned, keys.privateKey, 'ed-2')
-    expect(sig.signature?.alg).toBe('ED25519')
-    expect(await verifyCanonicalPayloadEd25519(payload, sig.signature?.value ?? '', keys.publicKey)).toBe(true)
-    expect(await verifyCanonicalPayloadEd25519(`${payload}x`, sig.signature?.value ?? '', keys.publicKey)).toBe(false)
-  })
-
-  it('flags expired messages', () => {
-    const unsigned = createEnvelope({
-      sender: 'agent.alpha',
-      intent: 'RESULT',
-      content: 'done',
-      messageId: 'm3',
-      nonce: 'n3',
-      nowMs: 0,
-      ttlMs: 100,
-    })
-    const diagnostics = validateEnvelope({ ...unsigned }, 500)
-    expect(diagnostics.some((d) => d.message === 'Message TTL expired')).toBe(true)
-  })
-})