@simulatte/doppler 0.1.0

package/src/config/schema/distill-training.schema.js

@@ -0,0 +1,139 @@
+export const DISTILL_STAGE_VALUES = Object.freeze(['stage_a', 'stage_b']);
+export const DISTILL_STUDENT_GRAPH_MODE_VALUES = Object.freeze(['projection_head', 'transformer_full']);
+
+export const DISTILL_TRAINING_SCHEMA_VERSION = 1;
+
+export const DEFAULT_DISTILL_FREEZE_GROUPS = Object.freeze({
+  encoder: false,
+  prior: false,
+  decoder: false,
+  base: false,
+  lora: false,
+});
+
+export const DEFAULT_DISTILL_TRAINING_CONFIG = Object.freeze({
+  schemaVersion: DISTILL_TRAINING_SCHEMA_VERSION,
+  enabled: false,
+  stage: 'stage_a',
+  teacherModelId: null,
+  studentModelId: null,
+  datasetId: null,
+  datasetPath: null,
+  languagePair: null,
+  sourceLangs: null,
+  targetLangs: null,
+  pairAllowlist: null,
+  strictPairContract: false,
+  shardIndex: null,
+  shardCount: null,
+  resumeFrom: null,
+  artifactDir: 'reports/training/distill',
+  stageAArtifact: null,
+  stageAArtifactHash: null,
+  temperature: 1,
+  alphaKd: 1,
+  alphaCe: 0,
+  allowHintFallback: false,
+  tripletMargin: 0.2,
+  studentGraphMode: 'transformer_full',
+  freeze: DEFAULT_DISTILL_FREEZE_GROUPS,
+});
+
+function assertFiniteNumber(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`Distill config: ${label} must be a finite number.`);
+  }
+}
+
+function assertBoolean(value, label) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`Distill config: ${label} must be a boolean.`);
+  }
+}
+
+function assertNullableString(value, label) {
+  if (value === null) return;
+  if (typeof value === 'string' && value.trim().length > 0) return;
+  throw new Error(`Distill config: ${label} must be a non-empty string or null.`);
+}
+
+function assertNullablePositiveInteger(value, label) {
+  if (value === null) return;
+  if (Number.isInteger(value) && value >= 1) return;
+  throw new Error(`Distill config: ${label} must be a positive integer or null.`);
+}
+
+function assertNullableStringArray(value, label) {
+  if (value === null) return;
+  if (!Array.isArray(value)) {
+    throw new Error(`Distill config: ${label} must be an array of strings or null.`);
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    if (typeof value[i] !== 'string' || value[i].trim().length === 0) {
+      throw new Error(`Distill config: ${label}[${i}] must be a non-empty string.`);
+    }
+  }
+}
+
+export function validateDistillTrainingConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('Distill config: expected an object.');
+  }
+  assertFiniteNumber(config.schemaVersion, 'schemaVersion');
+  assertBoolean(config.enabled, 'enabled');
+  if (!DISTILL_STAGE_VALUES.includes(config.stage)) {
+    throw new Error(`Distill config: stage must be one of ${DISTILL_STAGE_VALUES.join(', ')}.`);
+  }
+  assertNullableString(config.teacherModelId, 'teacherModelId');
+  assertNullableString(config.studentModelId, 'studentModelId');
+  assertNullableString(config.datasetId, 'datasetId');
+  assertNullableString(config.datasetPath, 'datasetPath');
+  assertNullableString(config.languagePair, 'languagePair');
+  assertNullableStringArray(config.sourceLangs, 'sourceLangs');
+  assertNullableStringArray(config.targetLangs, 'targetLangs');
+  assertNullableStringArray(config.pairAllowlist, 'pairAllowlist');
+  assertBoolean(config.strictPairContract, 'strictPairContract');
+  assertNullablePositiveInteger(config.shardIndex, 'shardIndex');
+  assertNullablePositiveInteger(config.shardCount, 'shardCount');
+  assertNullableString(config.resumeFrom, 'resumeFrom');
+  assertNullableString(config.artifactDir, 'artifactDir');
+  assertNullableString(config.stageAArtifact, 'stageAArtifact');
+  assertNullableString(config.stageAArtifactHash, 'stageAArtifactHash');
+  assertFiniteNumber(config.temperature, 'temperature');
+  assertFiniteNumber(config.alphaKd, 'alphaKd');
+  assertFiniteNumber(config.alphaCe, 'alphaCe');
+  assertBoolean(config.allowHintFallback, 'allowHintFallback');
+  assertFiniteNumber(config.tripletMargin, 'tripletMargin');
+  assertNullableString(config.studentGraphMode, 'studentGraphMode');
+  if (
+    config.studentGraphMode !== null
+    && !DISTILL_STUDENT_GRAPH_MODE_VALUES.includes(config.studentGraphMode)
+  ) {
+    throw new Error(
+      `Distill config: studentGraphMode must be one of ${DISTILL_STUDENT_GRAPH_MODE_VALUES.join(', ')} or null.`
+    );
+  }
+
+  const freeze = config.freeze;
+  if (!freeze || typeof freeze !== 'object' || Array.isArray(freeze)) {
+    throw new Error('Distill config: freeze must be an object.');
+  }
+  assertBoolean(freeze.encoder, 'freeze.encoder');
+  assertBoolean(freeze.prior, 'freeze.prior');
+  assertBoolean(freeze.decoder, 'freeze.decoder');
+  assertBoolean(freeze.base, 'freeze.base');
+  assertBoolean(freeze.lora, 'freeze.lora');
+
+  if (config.stage === 'stage_b' && !config.stageAArtifact) {
+    throw new Error('Distill config: stage_b requires stageAArtifact.');
+  }
+  if (
+    config.shardIndex !== null
+    && config.shardCount !== null
+    && config.shardIndex > config.shardCount
+  ) {
+    throw new Error('Distill config: shardIndex must be <= shardCount.');
+  }
+
+  return config;
+}

package/src/config/schema/distribution.schema.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Distribution Config Schema
+ *
+ * Configuration for network downloads, CDN settings, and retry policies.
+ * These values control how model shards are fetched from remote servers.
+ *
+ * @module config/schema/distribution
+ */
+
+/**
+ * Configuration for network distribution and download behavior.
+ *
+ * Controls concurrent downloads, retry policies, chunk sizes, and CDN routing.
+ * These settings affect network performance and reliability when fetching
+ * model shards from remote servers.
+ */
+export interface DistributionConfigSchema {
+  /** Number of concurrent shard downloads (1-8) */
+  concurrentDownloads: number;
+
+  /** Maximum retry attempts for failed downloads */
+  maxRetries: number;
+
+  /** Initial delay before first retry in milliseconds */
+  initialRetryDelayMs: number;
+
+  /** Maximum delay between retries in milliseconds (exponential backoff cap) */
+  maxRetryDelayMs: number;
+
+  /** Maximum chunk size for streaming downloads in bytes */
+  maxChunkSizeBytes: number;
+
+  /** CDN base path override (null uses origin server) */
+  cdnBasePath: string | null;
+
+  /** Ordered list of shard delivery sources */
+  sourceOrder: ('cache' | 'p2p' | 'http')[];
+
+  /** Canonical source transition matrix for fallback behavior */
+  sourceMatrix: {
+    cache: {
+      onHit: 'return';
+      onMiss: 'next' | 'terminal';
+      onFailure: 'next' | 'terminal';
+    };
+    p2p: {
+      onHit: 'return';
+      onMiss: 'next' | 'terminal';
+      onFailure: 'next' | 'terminal';
+    };
+    http: {
+      onHit: 'return';
+      onMiss: 'next' | 'terminal';
+      onFailure: 'next' | 'terminal';
+    };
+  };
+
+  /** Deterministic source decision and trace policy */
+  sourceDecision: {
+    /** Keep routing deterministic for identical config/capabilities */
+    deterministic: boolean;
+    /** Optional per-shard decision trace */
+    trace: {
+      /** Emit source decision trace in shard delivery result */
+      enabled: boolean;
+      /** Include skipped sources in the trace plan */
+      includeSkippedSources: boolean;
+      /** Deterministic sampling ratio in [0, 1] for trace emission */
+      samplingRate: number;
+    };
+  };
+
+  /** Anti-rollback guard policy for cross-source fallback */
+  antiRollback: {
+    /** Enable guard checks for fallback transitions */
+    enabled: boolean;
+    /** Require expected shard hash before source attempts */
+    requireExpectedHash: boolean;
+    /** Require expected shard size before source attempts */
+    requireExpectedSize: boolean;
+    /** Require expected manifest version-set before source attempts */
+    requireManifestVersionSet: boolean;
+  };
+
+  /** Optional P2P delivery configuration */
+  p2p: {
+    /** Enable P2P delivery attempts */
+    enabled: boolean;
+    /** Per-peer timeout in milliseconds */
+    timeoutMs: number;
+    /** Number of P2P retries before fallback */
+    maxRetries: number;
+    /** Delay between P2P retries in milliseconds */
+    retryDelayMs: number;
+    /** Versioned transport contract */
+    contractVersion: number;
+    /** Optional runtime-provided transport callback */
+    transport: unknown;
+    /** Optional control-plane callbacks for session + policy decisions */
+    controlPlane: {
+      /** Enable control-plane hooks */
+      enabled: boolean;
+      /** Versioned control-plane callback contract */
+      contractVersion: number;
+      /** Proactive token refresh skew in milliseconds */
+      tokenRefreshSkewMs: number;
+      /** Optional callback to issue/refresh session token */
+      tokenProvider: unknown;
+      /** Optional callback to allow/deny a shard request */
+      policyEvaluator: unknown;
+    };
+    /** Feature-flagged browser WebRTC data-plane transport slice */
+    webrtc: {
+      /** Enable browser WebRTC data-plane transport */
+      enabled: boolean;
+      /** Optional static peer id */
+      peerId: string | null;
+      /** Data-channel request timeout in milliseconds */
+      requestTimeoutMs: number;
+      /** Max accepted payload size in bytes */
+      maxPayloadBytes: number;
+      /** Optional peer selector callback */
+      selectPeer: unknown;
+      /** Callback for obtaining open RTCDataChannel */
+      getDataChannel: unknown;
+    };
+    /** Session/auth policy for P2P attempts */
+    security: {
+      /** Require a non-empty session token for P2P attempts */
+      requireSessionToken: boolean;
+      /** Session token value passed through runtime config */
+      sessionToken: string | null;
+      /** Optional absolute expiration timestamp (epoch ms) */
+      tokenExpiresAtMs: number | null;
+    };
+    /** Runtime abuse controls for P2P attempts */
+    abuse: {
+      /** Max transport requests per minute (0 disables) */
+      rateLimitPerMinute: number;
+      /** Consecutive failures before temporary quarantine */
+      maxConsecutiveFailures: number;
+      /** Quarantine duration in milliseconds */
+      quarantineMs: number;
+    };
+  };
+
+  /** Minimum interval between progress callbacks in milliseconds */
+  progressUpdateIntervalMs: number;
+
+  /** Require a specific Content-Encoding for shard downloads (null disables check) */
+  requiredContentEncoding: string | null;
+}
+
+/** Default distribution configuration */
+export declare const DEFAULT_DISTRIBUTION_CONFIG: DistributionConfigSchema;

package/src/config/schema/distribution.schema.js

@@ -0,0 +1,81 @@
+import { MB } from './units.schema.js';
+
+// =============================================================================
+// Distribution Config
+// =============================================================================
+
+export const DEFAULT_DISTRIBUTION_CONFIG = {
+  concurrentDownloads: 3,
+  maxRetries: 3,
+  initialRetryDelayMs: 1000,
+  maxRetryDelayMs: 30000,
+  maxChunkSizeBytes: 8 * MB,
+  cdnBasePath: null,
+  sourceOrder: ['cache', 'p2p', 'http'],
+  sourceMatrix: {
+    cache: {
+      onHit: 'return',
+      onMiss: 'next',
+      onFailure: 'next',
+    },
+    p2p: {
+      onHit: 'return',
+      onMiss: 'next',
+      onFailure: 'next',
+    },
+    http: {
+      onHit: 'return',
+      onMiss: 'terminal',
+      onFailure: 'terminal',
+    },
+  },
+  sourceDecision: {
+    deterministic: true,
+    trace: {
+      enabled: false,
+      includeSkippedSources: true,
+      samplingRate: 1,
+    },
+  },
+  antiRollback: {
+    enabled: true,
+    requireExpectedHash: true,
+    requireExpectedSize: false,
+    requireManifestVersionSet: true,
+  },
+  p2p: {
+    enabled: false,
+    timeoutMs: 3000,
+    maxRetries: 1,
+    retryDelayMs: 250,
+    contractVersion: 1,
+    transport: null,
+    controlPlane: {
+      enabled: false,
+      contractVersion: 1,
+      tokenRefreshSkewMs: 5000,
+      tokenProvider: null,
+      policyEvaluator: null,
+    },
+    webrtc: {
+      enabled: false,
+      peerId: null,
+      requestTimeoutMs: 2500,
+      maxPayloadBytes: 67108864,
+      selectPeer: null,
+      getDataChannel: null,
+    },
+    security: {
+      requireSessionToken: false,
+      sessionToken: null,
+      tokenExpiresAtMs: null,
+    },
+    abuse: {
+      rateLimitPerMinute: 0,
+      maxConsecutiveFailures: 3,
+      quarantineMs: 30000,
+    },
+  },
+  progressUpdateIntervalMs: 100,
+  requiredContentEncoding: null,
+};

package/src/config/schema/doppler.schema.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Doppler Config Schema
+ *
+ * Master configuration schema that composes all runtime configs together.
+ * This provides a single unified interface for configuring the entire
+ * Doppler inference engine.
+ *
+ * Individual configs remain importable for subsystems that only need
+ * their specific domain. This master config is for:
+ * - Serializing/restoring full engine state
+ * - Configuration management UIs
+ * - Debugging/logging full config state
+ *
+ * @module config/schema/doppler
+ */
+
+import type { ResolvedConfigSchema } from './preset.schema.js';
+import type { LoadingConfigSchema } from './loading.schema.js';
+import type { InferenceDefaultsConfigSchema } from './inference-defaults.schema.js';
+import type { SharedRuntimeConfigSchema } from './shared-runtime.schema.js';
+import type { EmulationConfigSchema } from './emulation.schema.js';
+
+/**
+ * Runtime configuration schema.
+ *
+ * Contains all configurable settings that are independent of the model.
+ * These settings control engine behavior regardless of which model is loaded.
+ */
+export interface RuntimeConfigSchema {
+  /** Cross-cutting runtime settings shared by loader + inference */
+  shared: SharedRuntimeConfigSchema;
+
+  /** OPFS paths, shard cache, memory management */
+  loading: LoadingConfigSchema;
+
+  /** Batching, sampling, tokenizer defaults */
+  inference: InferenceDefaultsConfigSchema;
+
+  /** NVIDIA superchip emulation settings */
+  emulation: EmulationConfigSchema;
+}
+
+/** Default runtime configuration */
+export declare const DEFAULT_RUNTIME_CONFIG: RuntimeConfigSchema;
+
+/**
+ * Master Doppler configuration schema.
+ *
+ * Combines model-specific configuration (resolved from preset + manifest)
+ * with runtime configuration (engine settings) and platform overrides.
+ */
+export interface DopplerConfigSchema {
+  /** Model-specific configuration (from preset + manifest) */
+  model?: ResolvedConfigSchema;
+
+  /** Runtime configuration (engine settings) */
+  runtime: RuntimeConfigSchema;
+}
+
+export interface DopplerConfigOverrides extends Partial<Omit<DopplerConfigSchema, 'runtime'>> {
+  runtime?: Partial<RuntimeConfigSchema>;
+}
+
+/** Default Doppler configuration (no model loaded) */
+export declare const DEFAULT_DOPPLER_CONFIG: DopplerConfigSchema;
+
+/**
+ * Create a Doppler configuration with optional overrides.
+ *
+ * Merges provided overrides with defaults, performing a deep merge
+ * on nested objects.
+ */
+export declare function createDopplerConfig(
+  overrides?: DopplerConfigOverrides
+): DopplerConfigSchema;