@simulatte/doppler 0.1.8 → 0.2.0

package/src/distribution/p2p-observability.d.ts

@@ -1,116 +0,0 @@
-export declare const P2P_OBSERVABILITY_SCHEMA_VERSION: 1;
-
-export interface P2PDeliveryObservabilityRecord {
-  schemaVersion: number;
-  timestampMs: number;
-  modelId: string | null;
-  shardIndex: number | null;
-  successSource: string | null;
-  attemptCount: number;
-  p2pAttempts: number;
-  httpAttempts: number;
-  cacheAttempts: number;
-  totalDurationMs: number;
-  p2pRttAvgMs: number | null;
-  httpRttAvgMs: number | null;
-  totalFailures: number;
-  fallbackToHttp: boolean;
-  p2pHit: boolean;
-  failureCodes: Record<string, number>;
-  rawMetrics: Record<string, unknown>;
-}
-
-export interface P2PObservabilitySummary {
-  schemaVersion: number;
-  generatedAtMs: number;
-  totals: {
-    records: number;
-    successful: number;
-    failed: number;
-    p2pHits: number;
-    httpFallbacks: number;
-  };
-  rates: {
-    availability: number;
-    p2pHitRate: number;
-    httpFallbackRate: number;
-  };
-  latencyMs: {
-    p50: number | null;
-    p95: number | null;
-    p99: number | null;
-  };
-  failureCodes: Record<string, number>;
-  slo: {
-    targets: {
-      minAvailability: number;
-      minP2PHitRate: number;
-      maxHttpFallbackRate: number;
-      maxP95LatencyMs: number;
-    };
-    breaches: Array<{
-      id: string;
-      metric: string;
-      expected: string;
-      actual: number;
-    }>;
-    status: 'pass' | 'fail';
-  };
-}
-
-export interface P2PObservabilityAlert {
-  schemaVersion: number;
-  id: string;
-  severity: 'warning' | 'critical';
-  message: string;
-  metric: string | null;
-  expected: string | null;
-  actual: number | null;
-  generatedAtMs: number;
-}
-
-export declare function createP2PDeliveryObservabilityRecord(
-  input: Record<string, unknown>,
-  context?: {
-    timestampMs?: number;
-    modelId?: string | null;
-    shardIndex?: number | null;
-  }
-): P2PDeliveryObservabilityRecord;
-
-export declare function aggregateP2PDeliveryObservability(
-  records?: Array<Record<string, unknown>>,
-  options?: {
-    targets?: {
-      minAvailability?: number;
-      minP2PHitRate?: number;
-      maxHttpFallbackRate?: number;
-      maxP95LatencyMs?: number;
-    };
-  }
-): P2PObservabilitySummary;
-
-export declare function buildP2PAlertsFromSummary(
-  summary: P2PObservabilitySummary,
-  options?: {
-    escalateBreaches?: string[];
-  }
-): P2PObservabilityAlert[];
-
-export declare function buildP2PDashboardSnapshot(
-  records?: Array<Record<string, unknown>>,
-  options?: {
-    targets?: {
-      minAvailability?: number;
-      minP2PHitRate?: number;
-      maxHttpFallbackRate?: number;
-      maxP95LatencyMs?: number;
-    };
-    escalateBreaches?: string[];
-  }
-): {
-  schemaVersion: number;
-  generatedAtMs: number;
-  summary: P2PObservabilitySummary;
-  alerts: P2PObservabilityAlert[];
-};

package/src/distribution/p2p-observability.js

@@ -1,303 +0,0 @@
-export const P2P_OBSERVABILITY_SCHEMA_VERSION = 1;
-
-const DEFAULT_SLO_TARGETS = Object.freeze({
-  minAvailability: 0.995,
-  minP2PHitRate: 0.5,
-  maxHttpFallbackRate: 0.5,
-  maxP95LatencyMs: 5000,
-});
-
-function asFiniteNumber(value, fallback = 0) {
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : fallback;
-}
-
-function assertFiniteNumber(value, label) {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed)) {
-    throw new Error(`P2P observability ${label} must be a finite number.`);
-  }
-  return parsed;
-}
-
-function asNonNegativeInteger(value, fallback = 0) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 0) {
-    return fallback;
-  }
-  return parsed;
-}
-
-function asStringOrNull(value) {
-  if (value === undefined || value === null) {
-    return null;
-  }
-  const normalized = String(value).trim();
-  return normalized || null;
-}
-
-function sumFailureCodes(failureCodes) {
-  if (!failureCodes || typeof failureCodes !== 'object') {
-    return 0;
-  }
-  let total = 0;
-  for (const value of Object.values(failureCodes)) {
-    total += asNonNegativeInteger(value, 0);
-  }
-  return total;
-}
-
-function mergeFailureCodes(into, failureCodes) {
-  if (!failureCodes || typeof failureCodes !== 'object') {
-    return;
-  }
-  for (const [code, rawCount] of Object.entries(failureCodes)) {
-    const key = asStringOrNull(code) ?? 'unknown';
-    const count = asNonNegativeInteger(rawCount, 0);
-    into[key] = (into[key] ?? 0) + count;
-  }
-}
-
-function percentile(values, ratio) {
-  if (!Array.isArray(values) || values.length === 0) {
-    return null;
-  }
-  const sorted = values
-    .filter((entry) => Number.isFinite(entry))
-    .sort((left, right) => left - right);
-  if (sorted.length === 0) {
-    return null;
-  }
-  if (sorted.length === 1) {
-    return sorted[0];
-  }
-  const index = Math.ceil(sorted.length * ratio) - 1;
-  const clampedIndex = Math.max(0, Math.min(sorted.length - 1, index));
-  return sorted[clampedIndex];
-}
-
-function resolveSLOTargets(options = {}) {
-  const hasExplicitTargets = Object.hasOwn(options, 'targets');
-  if (hasExplicitTargets && (options.targets == null || typeof options.targets !== 'object' || Array.isArray(options.targets))) {
-    throw new Error('P2P observability targets must be an object when provided.');
-  }
-  const targets = hasExplicitTargets ? options.targets : {};
-
-  const minAvailability = Object.hasOwn(targets, 'minAvailability')
-    ? assertFiniteNumber(targets.minAvailability, 'targets.minAvailability')
-    : DEFAULT_SLO_TARGETS.minAvailability;
-  const minP2PHitRate = Object.hasOwn(targets, 'minP2PHitRate')
-    ? assertFiniteNumber(targets.minP2PHitRate, 'targets.minP2PHitRate')
-    : DEFAULT_SLO_TARGETS.minP2PHitRate;
-  const maxHttpFallbackRate = Object.hasOwn(targets, 'maxHttpFallbackRate')
-    ? assertFiniteNumber(targets.maxHttpFallbackRate, 'targets.maxHttpFallbackRate')
-    : DEFAULT_SLO_TARGETS.maxHttpFallbackRate;
-  const maxP95LatencyMs = Object.hasOwn(targets, 'maxP95LatencyMs')
-    ? assertFiniteNumber(targets.maxP95LatencyMs, 'targets.maxP95LatencyMs')
-    : DEFAULT_SLO_TARGETS.maxP95LatencyMs;
-
-  if (minAvailability < 0 || minAvailability > 1) {
-    throw new Error('P2P observability targets.minAvailability must be between 0 and 1.');
-  }
-  if (minP2PHitRate < 0 || minP2PHitRate > 1) {
-    throw new Error('P2P observability targets.minP2PHitRate must be between 0 and 1.');
-  }
-  if (maxHttpFallbackRate < 0 || maxHttpFallbackRate > 1) {
-    throw new Error('P2P observability targets.maxHttpFallbackRate must be between 0 and 1.');
-  }
-  if (maxP95LatencyMs < 0) {
-    throw new Error('P2P observability targets.maxP95LatencyMs must be >= 0.');
-  }
-
-  return {
-    minAvailability,
-    minP2PHitRate,
-    maxHttpFallbackRate,
-    maxP95LatencyMs,
-  };
-}
-
-function normalizeDeliveryMetrics(input) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('P2P observability requires an object payload.');
-  }
-  const metrics = input.deliveryMetrics && typeof input.deliveryMetrics === 'object'
-    ? input.deliveryMetrics
-    : input;
-  if (!metrics || typeof metrics !== 'object') {
-    throw new Error('P2P observability metrics payload is missing deliveryMetrics.');
-  }
-  return metrics;
-}
-
-export function createP2PDeliveryObservabilityRecord(input, context = {}) {
-  const metrics = normalizeDeliveryMetrics(input);
-  const sourceAttempts = metrics.sourceAttempts && typeof metrics.sourceAttempts === 'object'
-    ? metrics.sourceAttempts
-    : {};
-  const p2pAttempts = asNonNegativeInteger(sourceAttempts.p2p, 0);
-  const httpAttempts = asNonNegativeInteger(sourceAttempts.http, 0);
-  const cacheAttempts = asNonNegativeInteger(sourceAttempts.cache, 0);
-  const successSource = asStringOrNull(metrics.successSource);
-  const attemptCount = asNonNegativeInteger(metrics.attemptCount, p2pAttempts + httpAttempts + cacheAttempts);
-  const totalDurationMs = asFiniteNumber(metrics.totalDurationMs, 0);
-  const p2pRttAvgMs = Number.isFinite(metrics?.p2pRttMs?.avg) ? metrics.p2pRttMs.avg : null;
-  const httpRttAvgMs = Number.isFinite(metrics?.httpRttMs?.avg) ? metrics.httpRttMs.avg : null;
-
-  return {
-    schemaVersion: P2P_OBSERVABILITY_SCHEMA_VERSION,
-    timestampMs: asNonNegativeInteger(context.timestampMs ?? Date.now(), Date.now()),
-    modelId: asStringOrNull(context.modelId),
-    shardIndex: Number.isInteger(context.shardIndex) ? context.shardIndex : null,
-    successSource,
-    attemptCount,
-    p2pAttempts,
-    httpAttempts,
-    cacheAttempts,
-    totalDurationMs,
-    p2pRttAvgMs,
-    httpRttAvgMs,
-    totalFailures: sumFailureCodes(metrics.failureCodes),
-    fallbackToHttp: successSource === 'http' && p2pAttempts > 0,
-    p2pHit: successSource === 'p2p',
-    failureCodes: metrics.failureCodes && typeof metrics.failureCodes === 'object'
-      ? { ...metrics.failureCodes }
-      : {},
-    rawMetrics: metrics,
-  };
-}
-
-export function aggregateP2PDeliveryObservability(records = [], options = {}) {
-  if (!Array.isArray(records)) {
-    throw new Error('P2P observability aggregate expects records array.');
-  }
-
-  const normalized = records.map((record) => createP2PDeliveryObservabilityRecord(record));
-  const total = normalized.length;
-  const successful = normalized.filter((record) => !!record.successSource).length;
-  const p2pHits = normalized.filter((record) => record.p2pHit).length;
-  const httpFallbacks = normalized.filter((record) => record.fallbackToHttp).length;
-  const durationValues = normalized.map((record) => record.totalDurationMs);
-
-  const failureCodes = {};
-  for (const record of normalized) {
-    mergeFailureCodes(failureCodes, record.failureCodes);
-  }
-
-  const targets = resolveSLOTargets(options);
-  const availability = total > 0 ? successful / total : 0;
-  const p2pHitRate = total > 0 ? p2pHits / total : 0;
-  const httpFallbackRate = total > 0 ? httpFallbacks / total : 0;
-  const p95LatencyMs = percentile(durationValues, 0.95);
-
-  const breaches = [];
-  if (availability < targets.minAvailability) {
-    breaches.push({
-      id: 'availability_breach',
-      metric: 'availability',
-      expected: `>= ${targets.minAvailability}`,
-      actual: availability,
-    });
-  }
-  if (p2pHitRate < targets.minP2PHitRate) {
-    breaches.push({
-      id: 'p2p_hit_rate_breach',
-      metric: 'p2pHitRate',
-      expected: `>= ${targets.minP2PHitRate}`,
-      actual: p2pHitRate,
-    });
-  }
-  if (httpFallbackRate > targets.maxHttpFallbackRate) {
-    breaches.push({
-      id: 'http_fallback_rate_breach',
-      metric: 'httpFallbackRate',
-      expected: `<= ${targets.maxHttpFallbackRate}`,
-      actual: httpFallbackRate,
-    });
-  }
-  if (p95LatencyMs != null && p95LatencyMs > targets.maxP95LatencyMs) {
-    breaches.push({
-      id: 'latency_p95_breach',
-      metric: 'p95LatencyMs',
-      expected: `<= ${targets.maxP95LatencyMs}`,
-      actual: p95LatencyMs,
-    });
-  }
-
-  return {
-    schemaVersion: P2P_OBSERVABILITY_SCHEMA_VERSION,
-    generatedAtMs: Date.now(),
-    totals: {
-      records: total,
-      successful,
-      failed: Math.max(0, total - successful),
-      p2pHits,
-      httpFallbacks,
-    },
-    rates: {
-      availability,
-      p2pHitRate,
-      httpFallbackRate,
-    },
-    latencyMs: {
-      p50: percentile(durationValues, 0.5),
-      p95: p95LatencyMs,
-      p99: percentile(durationValues, 0.99),
-    },
-    failureCodes,
-    slo: {
-      targets,
-      breaches,
-      status: breaches.length === 0 ? 'pass' : 'fail',
-    },
-  };
-}
-
-export function buildP2PAlertsFromSummary(summary, options = {}) {
-  if (!summary || typeof summary !== 'object') {
-    throw new Error('P2P observability alert builder requires summary object.');
-  }
-
-  const severityByBreach = {
-    availability_breach: 'critical',
-    p2p_hit_rate_breach: 'warning',
-    http_fallback_rate_breach: 'warning',
-    latency_p95_breach: 'warning',
-  };
-  const escalatedBreaches = new Set(Array.isArray(options.escalateBreaches)
-    ? options.escalateBreaches.map((entry) => asStringOrNull(entry)).filter(Boolean)
-    : []);
-
-  const breaches = Array.isArray(summary?.slo?.breaches)
-    ? summary.slo.breaches
-    : [];
-
-  return breaches.map((breach) => {
-    const id = asStringOrNull(breach.id) ?? 'unknown_breach';
-    const baseSeverity = severityByBreach[id] ?? 'warning';
-    const severity = escalatedBreaches.has(id)
-      ? 'critical'
-      : baseSeverity;
-    return {
-      schemaVersion: P2P_OBSERVABILITY_SCHEMA_VERSION,
-      id,
-      severity,
-      message: `P2P SLO breach (${id}): expected ${breach.expected}, actual ${breach.actual}.`,
-      metric: breach.metric ?? null,
-      expected: breach.expected ?? null,
-      actual: breach.actual ?? null,
-      generatedAtMs: Date.now(),
-    };
-  });
-}
-
-export function buildP2PDashboardSnapshot(records = [], options = {}) {
-  const summary = aggregateP2PDeliveryObservability(records, options);
-  const alerts = buildP2PAlertsFromSummary(summary, options);
-  return {
-    schemaVersion: P2P_OBSERVABILITY_SCHEMA_VERSION,
-    generatedAtMs: Date.now(),
-    summary,
-    alerts,
-  };
-}

package/src/distribution/p2p-transport-contract.d.ts

@@ -1,57 +0,0 @@
-export declare const P2P_TRANSPORT_CONTRACT_VERSION: 1;
-export declare const P2P_TRANSPORT_RESULT_SCHEMA_VERSION: 1;
-
-export declare const P2P_TRANSPORT_ERROR_CODES: Readonly<{
-  unconfigured: string;
-  unavailable: string;
-  timeout: string;
-  aborted: string;
-  integrityMismatch: string;
-  policyDenied: string;
-  internal: string;
-  payloadInvalid: string;
-  contractUnsupported: string;
-}>;
-
-export interface P2PTransportError extends Error {
-  code?: string;
-  retryable?: boolean;
-  details?: Record<string, unknown>;
-}
-
-export declare function createP2PTransportError(
-  code: string,
-  message: string,
-  details?: Record<string, unknown> | null,
-  retryable?: boolean
-): P2PTransportError;
-
-export declare function assertSupportedP2PTransportContract(
-  version: number | null | undefined
-): number;
-
-export interface P2PTransportResultEnvelope {
-  schemaVersion: number;
-  data: ArrayBuffer;
-  manifestVersionSet: string | null;
-  manifestHash: string | null;
-  rangeStart: number | null;
-  totalSize: number | null;
-}
-
-export declare function normalizeP2PTransportResult(
-  value: unknown,
-  label?: string
-): P2PTransportResultEnvelope | null;
-
-export declare function normalizeP2PTransportPayload(
-  value: unknown,
-  label?: string
-): ArrayBuffer | null;
-
-export declare function normalizeP2PTransportError(
-  error: unknown,
-  context?: Record<string, unknown>
-): P2PTransportError;
-
-export declare function isP2PTransportRetryable(error: unknown): boolean;