@simulatte/doppler 0.1.0

package/src/diffusion/index.js

@@ -0,0 +1,8 @@
+export { DiffusionPipeline, createDiffusionPipeline } from '../inference/pipelines/diffusion/pipeline.js';
+export { createDiffusionWeightLoader } from '../inference/pipelines/diffusion/weights.js';
+export { mergeDiffusionConfig, initializeDiffusion } from '../inference/pipelines/diffusion/init.js';
+export {
+  computeImageFingerprint,
+  computeImageRegressionMetrics,
+  assertImageRegressionWithinTolerance,
+} from './image-regression.js';

package/src/distribution/p2p-control-plane.d.ts

@@ -0,0 +1,52 @@
+export declare const P2P_CONTROL_PLANE_CONTRACT_VERSION: 1;
+
+export interface P2PControlPlaneSessionUpdate {
+  hasSessionToken: boolean;
+  hasTokenExpiresAtMs: boolean;
+  sessionToken: string | null;
+  tokenExpiresAtMs: number | null;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface P2PPolicyDecision {
+  allow: boolean;
+  reason: string | null;
+  sessionUpdate: P2PControlPlaneSessionUpdate | null;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface P2PControlPlaneConfig {
+  enabled: boolean;
+  contractVersion: number;
+  tokenRefreshSkewMs: number;
+  tokenProvider: ((context: Record<string, unknown>) => Promise<unknown> | unknown) | null;
+  policyEvaluator: ((context: Record<string, unknown>) => Promise<unknown> | unknown) | null;
+}
+
+export declare function assertSupportedP2PControlPlaneContract(
+  version: number | null | undefined
+): number;
+
+export declare function normalizeControlPlaneSessionUpdate(
+  value: unknown,
+  label?: string
+): P2PControlPlaneSessionUpdate | null;
+
+export declare function normalizeP2PPolicyDecision(
+  value: unknown,
+  label?: string
+): P2PPolicyDecision;
+
+export declare function normalizeP2PControlPlaneConfig(
+  config?: Record<string, unknown>
+): P2PControlPlaneConfig;
+
+export declare function resolveP2PSessionToken(
+  controlPlaneConfig: P2PControlPlaneConfig,
+  context?: Record<string, unknown>
+): Promise<P2PControlPlaneSessionUpdate | null>;
+
+export declare function evaluateP2PPolicyDecision(
+  controlPlaneConfig: P2PControlPlaneConfig,
+  context?: Record<string, unknown>
+): Promise<P2PPolicyDecision>;

package/src/distribution/p2p-control-plane.js

@@ -0,0 +1,232 @@
+import {
+  P2P_TRANSPORT_ERROR_CODES,
+  createP2PTransportError,
+  normalizeP2PTransportError,
+} from './p2p-transport-contract.js';
+
+export const P2P_CONTROL_PLANE_CONTRACT_VERSION = 1;
+
+const DEFAULT_TOKEN_REFRESH_SKEW_MS = 5000;
+
+function asOptionalString(value, label) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value !== 'string') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must be a string when provided.`,
+      { label }
+    );
+  }
+  const normalized = value.trim();
+  return normalized || null;
+}
+
+function asOptionalTimestamp(value, label) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must be a positive timestamp when provided.`,
+      { label }
+    );
+  }
+  return Math.floor(parsed);
+}
+
+function asNonNegativeInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+export function assertSupportedP2PControlPlaneContract(version) {
+  const parsed = Number(version ?? P2P_CONTROL_PLANE_CONTRACT_VERSION);
+  if (!Number.isInteger(parsed) || parsed !== P2P_CONTROL_PLANE_CONTRACT_VERSION) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.contractUnsupported,
+      `Unsupported p2p.controlPlane contractVersion "${version}". Supported: ${P2P_CONTROL_PLANE_CONTRACT_VERSION}.`,
+      { contractVersion: version }
+    );
+  }
+  return parsed;
+}
+
+export function normalizeControlPlaneSessionUpdate(value, label = 'p2p control-plane session update') {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === 'string') {
+    const sessionToken = asOptionalString(value, `${label}.sessionToken`);
+    return {
+      hasSessionToken: true,
+      hasTokenExpiresAtMs: false,
+      sessionToken,
+      tokenExpiresAtMs: null,
+      metadata: null,
+    };
+  }
+  if (typeof value !== 'object') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must be a string or object when provided.`,
+      { label }
+    );
+  }
+
+  const sessionToken = asOptionalString(
+    value.sessionToken ?? value.token,
+    `${label}.sessionToken`
+  );
+  const tokenExpiresAtMs = asOptionalTimestamp(
+    value.tokenExpiresAtMs,
+    `${label}.tokenExpiresAtMs`
+  );
+  const metadata = value.metadata && typeof value.metadata === 'object'
+    ? value.metadata
+    : null;
+
+  return {
+    hasSessionToken: Object.prototype.hasOwnProperty.call(value, 'sessionToken')
+      || Object.prototype.hasOwnProperty.call(value, 'token'),
+    hasTokenExpiresAtMs: Object.prototype.hasOwnProperty.call(value, 'tokenExpiresAtMs'),
+    sessionToken,
+    tokenExpiresAtMs,
+    metadata,
+  };
+}
+
+export function normalizeP2PPolicyDecision(value, label = 'p2p control-plane policy decision') {
+  if (value === undefined || value === null) {
+    return {
+      allow: true,
+      reason: null,
+      sessionUpdate: null,
+      metadata: null,
+    };
+  }
+
+  if (typeof value === 'boolean') {
+    return {
+      allow: value,
+      reason: value ? null : 'policy_denied',
+      sessionUpdate: null,
+      metadata: null,
+    };
+  }
+
+  if (typeof value !== 'object') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must be a boolean or object when provided.`,
+      { label }
+    );
+  }
+
+  const allow = value.allow === false || value.deny === true
+    ? false
+    : true;
+  const reason = asOptionalString(value.reason, `${label}.reason`);
+  const sessionUpdate = normalizeControlPlaneSessionUpdate(
+    {
+      sessionToken: value.sessionToken,
+      token: value.token,
+      tokenExpiresAtMs: value.tokenExpiresAtMs,
+      metadata: value.sessionMetadata,
+    },
+    `${label}.sessionUpdate`
+  );
+  const metadata = value.metadata && typeof value.metadata === 'object'
+    ? value.metadata
+    : null;
+
+  return {
+    allow,
+    reason: reason ?? (allow ? null : 'policy_denied'),
+    sessionUpdate,
+    metadata,
+  };
+}
+
+export function normalizeP2PControlPlaneConfig(config = {}) {
+  const raw = config && typeof config === 'object'
+    ? config
+    : {};
+
+  const tokenProvider = typeof raw.tokenProvider === 'function'
+    ? raw.tokenProvider
+    : null;
+  const policyEvaluator = typeof raw.policyEvaluator === 'function'
+    ? raw.policyEvaluator
+    : null;
+  const hasWiring = tokenProvider || policyEvaluator;
+  const enabled = raw.enabled === true || !!hasWiring;
+
+  if (raw.enabled === true && !hasWiring) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.unconfigured,
+      'p2p.controlPlane.enabled=true requires tokenProvider and/or policyEvaluator callbacks.'
+    );
+  }
+
+  return {
+    enabled,
+    contractVersion: assertSupportedP2PControlPlaneContract(
+      raw.contractVersion ?? P2P_CONTROL_PLANE_CONTRACT_VERSION
+    ),
+    tokenRefreshSkewMs: asNonNegativeInteger(raw.tokenRefreshSkewMs, DEFAULT_TOKEN_REFRESH_SKEW_MS),
+    tokenProvider,
+    policyEvaluator,
+  };
+}
+
+export async function resolveP2PSessionToken(controlPlaneConfig, context = {}) {
+  if (!controlPlaneConfig?.enabled || typeof controlPlaneConfig.tokenProvider !== 'function') {
+    return null;
+  }
+
+  try {
+    const response = await controlPlaneConfig.tokenProvider({
+      contractVersion: controlPlaneConfig.contractVersion,
+      ...context,
+    });
+    return normalizeControlPlaneSessionUpdate(response, 'p2p control-plane token provider response');
+  } catch (error) {
+    throw normalizeP2PTransportError(error, {
+      stage: 'control_plane_token_provider',
+      shardIndex: context?.shardIndex ?? null,
+      attempt: context?.attempt ?? null,
+    });
+  }
+}
+
+export async function evaluateP2PPolicyDecision(controlPlaneConfig, context = {}) {
+  if (!controlPlaneConfig?.enabled || typeof controlPlaneConfig.policyEvaluator !== 'function') {
+    return {
+      allow: true,
+      reason: null,
+      sessionUpdate: null,
+      metadata: null,
+    };
+  }
+
+  try {
+    const response = await controlPlaneConfig.policyEvaluator({
+      contractVersion: controlPlaneConfig.contractVersion,
+      ...context,
+    });
+    return normalizeP2PPolicyDecision(response, 'p2p control-plane policy evaluator response');
+  } catch (error) {
+    throw normalizeP2PTransportError(error, {
+      stage: 'control_plane_policy_evaluator',
+      shardIndex: context?.shardIndex ?? null,
+      attempt: context?.attempt ?? null,
+    });
+  }
+}

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

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

@@ -0,0 +1,267 @@
+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 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 targets = options.targets && typeof options.targets === 'object'
+    ? options.targets
+    : {};
+
+  return {
+    minAvailability: asFiniteNumber(targets.minAvailability, DEFAULT_SLO_TARGETS.minAvailability),
+    minP2PHitRate: asFiniteNumber(targets.minP2PHitRate, DEFAULT_SLO_TARGETS.minP2PHitRate),
+    maxHttpFallbackRate: asFiniteNumber(targets.maxHttpFallbackRate, DEFAULT_SLO_TARGETS.maxHttpFallbackRate),
+    maxP95LatencyMs: asFiniteNumber(targets.maxP95LatencyMs, DEFAULT_SLO_TARGETS.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,
+  };
+}