@simulatte/doppler 0.1.0

package/src/gpu/weight-buffer.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Weight Buffer Abstraction
+ *
+ * Wraps GPUBuffer with weight-specific metadata (dtype, layout).
+ * Parallel to Tensor but for weights which have:
+ * - Quantized dtypes (q4k, q8, bf16)
+ * - Layout metadata (row/column for transposeB)
+ *
+ * Use Tensor for activations (f16/f32 flowing through pipeline).
+ * Use WeightBuffer for model weights (static, may be quantized).
+ */
+
+export type WeightDtype = 'f16' | 'f32' | 'bf16' | 'q4k' | 'q8';
+export type WeightLayout = 'row' | 'column';
+
+/**
+ * CPU-resident weight buffer with layout metadata.
+ * Used for oversized weights that cannot be bound as a single GPU buffer.
+ */
+export interface CpuWeightBuffer {
+  readonly data: Float32Array;
+  readonly dtype: WeightDtype;
+  readonly layout: WeightLayout;
+  readonly shape: readonly number[];
+  readonly label?: string;
+}
+
+/**
+ * A weight buffer with explicit dtype and layout.
+ * Use this instead of raw GPUBuffer for weight matrices.
+ */
+export interface WeightBuffer {
+  readonly buffer: GPUBuffer;
+  readonly dtype: WeightDtype;
+  readonly layout: WeightLayout;
+  readonly shape: readonly number[];
+  readonly label?: string;
+}
+
+/**
+ * Tensor-like buffer with dtype + shape metadata.
+ * Used by matmul when activations are passed in place of weights.
+ */
+export interface TensorLike {
+  readonly buffer: GPUBuffer;
+  readonly dtype: 'f16' | 'f32';
+  readonly shape: readonly number[];
+  readonly label?: string;
+}
+
+/**
+ * Attach runtime dtype metadata to a raw GPUBuffer.
+ * Used when non-matmul paths keep plain GPUBuffer values.
+ */
+export function tagBufferDtype(buffer: GPUBuffer, dtype: string): void;
+
+/**
+ * Read runtime dtype metadata from a raw GPUBuffer.
+ */
+export function getBufferDtype(buffer: GPUBuffer): string | null;
+
+/**
+ * Create a weight buffer from a GPU buffer with explicit metadata.
+ */
+export function createWeightBuffer(
+  buffer: GPUBuffer,
+  dtype: WeightDtype,
+  layout: WeightLayout,
+  shape: number[],
+  label?: string
+): WeightBuffer;
+
+/**
+ * Create a CPU-resident weight buffer with explicit metadata.
+ */
+export function createCpuWeightBuffer(
+  data: Float32Array,
+  dtype: WeightDtype,
+  layout: WeightLayout,
+  shape: number[],
+  label?: string
+): CpuWeightBuffer;
+
+/**
+ * Check if weight is stored in column-major (pre-transposed) format.
+ * Column-major weights use transposeB=false in matmul.
+ */
+export function isColumnMajor(weight: WeightBuffer): boolean;
+
+/**
+ * Check if weight buffer is a specific type for type guards.
+ */
+export function isWeightBuffer(value: unknown): value is WeightBuffer;
+
+/**
+ * Check if value is a CPU-resident weight buffer.
+ */
+export function isCpuWeightBuffer(value: unknown): value is CpuWeightBuffer;
+
+/**
+ * Extract the raw GPUBuffer from either a WeightBuffer or raw GPUBuffer.
+ * Used for backwards compatibility during migration.
+ */
+export function getBuffer(weight: GPUBuffer | WeightBuffer | TensorLike): GPUBuffer;
+
+/**
+ * Get layout from WeightBuffer, or null for raw GPUBuffer.
+ * Used for auto-resolving transposeB in matmul.
+ */
+export function getLayout(weight: GPUBuffer | WeightBuffer | TensorLike): WeightLayout | null;
+
+/**
+ * Get dtype from WeightBuffer, or null for raw GPUBuffer.
+ */
+export function getWeightDtype(weight: GPUBuffer | WeightBuffer | TensorLike): WeightDtype | TensorLike['dtype'] | null;

package/src/gpu/weight-buffer.js

@@ -0,0 +1,118 @@
+
+
+const bufferDtypes = new WeakMap();
+
+function canTrackBuffer(buffer) {
+  return typeof GPUBuffer !== 'undefined' && buffer instanceof GPUBuffer;
+}
+
+function normalizeDtype(dtype) {
+  if (typeof dtype !== 'string') return null;
+  const value = dtype.toLowerCase();
+  return value.length > 0 ? value : null;
+}
+
+export function tagBufferDtype(buffer, dtype) {
+  if (!canTrackBuffer(buffer)) return;
+  const normalized = normalizeDtype(dtype);
+  if (!normalized) return;
+  bufferDtypes.set(buffer, normalized);
+}
+
+export function getBufferDtype(buffer) {
+  if (!canTrackBuffer(buffer)) return null;
+  return bufferDtypes.get(buffer) ?? null;
+}
+
+
+export function createWeightBuffer(
+  buffer,
+  dtype,
+  layout,
+  shape,
+  label
+) {
+  tagBufferDtype(buffer, dtype);
+  return {
+    buffer,
+    dtype,
+    layout,
+    shape: Object.freeze([...shape]),
+    label,
+  };
+}
+
+
+export function createCpuWeightBuffer(
+  data,
+  dtype,
+  layout,
+  shape,
+  label
+) {
+  return {
+    data,
+    dtype,
+    layout,
+    shape: Object.freeze([...shape]),
+    label,
+  };
+}
+
+
+export function isColumnMajor(weight) {
+  return weight.layout === 'column';
+}
+
+
+export function isWeightBuffer(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'buffer' in value &&
+    'dtype' in value &&
+    'layout' in value &&
+    'shape' in value
+  );
+}
+
+
+export function isCpuWeightBuffer(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'data' in value &&
+    'dtype' in value &&
+    'layout' in value &&
+    'shape' in value
+  );
+}
+
+function isTensorLike(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'buffer' in value &&
+    'dtype' in value &&
+    'shape' in value
+  );
+}
+
+
+export function getBuffer(weight) {
+  if (isWeightBuffer(weight)) return weight.buffer;
+  if (isTensorLike(weight)) return weight.buffer;
+  return weight;
+}
+
+
+export function getLayout(weight) {
+  return isWeightBuffer(weight) ? weight.layout : null;
+}
+
+
+export function getWeightDtype(weight) {
+  if (isWeightBuffer(weight)) return weight.dtype;
+  if (isTensorLike(weight)) return weight.dtype;
+  return null;
+}

package/src/hotswap/intent-bundle.d.ts

@@ -0,0 +1,37 @@
+import type { Manifest } from '../config/schema/manifest.schema.js';
+
+export interface IntentBundleVerifyContext {
+  manifest?: Manifest | null;
+  kernelRegistryVersion?: string | null;
+  enforceDeterministicOutput?: boolean;
+}
+
+export interface IntentBundleVerificationResult {
+  ok: boolean;
+  reason: string;
+  reasons?: string[];
+}
+
+export interface IntentBundleDriftResult {
+  ok: boolean;
+  drift: number;
+  matchRatio: number;
+  reason: string;
+}
+
+export declare function fetchIntentBundle(url: string): Promise<Record<string, unknown>>;
+export declare function computeManifestHash(manifest: Manifest): Promise<string>;
+export declare function getKernelRegistryVersion(): Promise<string | null>;
+export declare function verifyIntentBundle(
+  bundle: Record<string, unknown>,
+  context: IntentBundleVerifyContext
+): Promise<IntentBundleVerificationResult>;
+export declare function compareTopK(
+  expectedTopK: number[],
+  actualTopK: number[]
+): { matchRatio: number; drift: number };
+export declare function enforceLogitDrift(
+  expectedTopK: number[],
+  actualTopK: number[],
+  maxDriftThreshold: number | null | undefined
+): IntentBundleDriftResult;

package/src/hotswap/intent-bundle.js

@@ -0,0 +1,123 @@
+import { getRegistry } from '../config/kernels/registry.js';
+import { log } from '../debug/index.js';
+
+export async function fetchIntentBundle(url) {
+  const response = await fetch(url, { cache: 'no-store' });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch intent bundle: ${response.status}`);
+  }
+  return response.json();
+}
+
+export async function computeManifestHash(manifest) {
+  const payload = stableStringify(manifest);
+  return await computeSha256Hex(payload);
+}
+
+export async function getKernelRegistryVersion() {
+  const registry = await getRegistry();
+  return registry?.version ?? null;
+}
+
+export async function verifyIntentBundle(bundle, context) {
+  const reasons = [];
+  if (!bundle || typeof bundle !== 'object') {
+    return { ok: false, reason: 'Invalid bundle', reasons: ['Bundle is not an object'] };
+  }
+
+  const foundation = bundle.foundation || {};
+  const constraints = bundle.constraints || {};
+  const payload = bundle.payload || {};
+
+  const baseModelHash = foundation.baseModelHash || foundation.base_model_hash;
+  const kernelRegistryVersion = foundation.kernelRegistryVersion || foundation.kernel_registry_version;
+
+  if (!baseModelHash) reasons.push('Missing foundation.baseModelHash');
+  if (!kernelRegistryVersion) reasons.push('Missing foundation.kernelRegistryVersion');
+
+  const deterministicRequired =
+    context?.enforceDeterministicOutput === true || constraints.enforceDeterministicOutput === true;
+
+  if (deterministicRequired && !payload.expectedOutputHash) {
+    reasons.push('Missing payload.expectedOutputHash');
+  }
+
+  if (context?.manifest && baseModelHash) {
+    const manifestHash = await computeManifestHash(context.manifest);
+    if (manifestHash !== baseModelHash.replace('sha256:', '')) {
+      reasons.push('Base model hash mismatch');
+    }
+  }
+
+  if (context?.kernelRegistryVersion && kernelRegistryVersion) {
+    if (context.kernelRegistryVersion !== kernelRegistryVersion) {
+      reasons.push('Kernel registry version mismatch');
+    }
+  }
+
+  if (reasons.length > 0) {
+    return { ok: false, reason: 'Intent bundle rejected', reasons };
+  }
+
+  return { ok: true, reason: 'Intent bundle accepted' };
+}
+
+export function compareTopK(expectedTopK, actualTopK) {
+  if (!Array.isArray(expectedTopK) || !Array.isArray(actualTopK) || expectedTopK.length === 0) {
+    return { matchRatio: 0, drift: 1 };
+  }
+
+  const expectedSet = new Set(expectedTopK);
+  const matches = actualTopK.filter((token) => expectedSet.has(token)).length;
+  const matchRatio = matches / Math.max(expectedTopK.length, 1);
+  return { matchRatio, drift: 1 - matchRatio };
+}
+
+export function enforceLogitDrift(expectedTopK, actualTopK, maxDriftThreshold) {
+  const { drift, matchRatio } = compareTopK(expectedTopK, actualTopK);
+  if (maxDriftThreshold == null) {
+    return { ok: true, drift, matchRatio, reason: 'No drift threshold provided' };
+  }
+  const ok = drift <= maxDriftThreshold;
+  return {
+    ok,
+    drift,
+    matchRatio,
+    reason: ok ? 'Drift within threshold' : 'Drift exceeds threshold'
+  };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+async function computeSha256Hex(value) {
+  const bytes = new TextEncoder().encode(value);
+  const subtle = globalThis.crypto?.subtle;
+
+  if (subtle) {
+    const hashBuffer = await subtle.digest('SHA-256', bytes);
+    return bytesToHex(new Uint8Array(hashBuffer));
+  }
+
+  throw new Error('WebCrypto/SHA-256 unavailable (secure context required)');
+}
+
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+
+  const record = value;
+  const keys = Object.keys(record).sort();
+  const entries = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+  return `{${entries.join(',')}}`;
+}

package/src/hotswap/manifest.d.ts

@@ -0,0 +1,33 @@
+import type { HashAlgorithm } from '../config/schema/index.js';
+import type { HotSwapConfigSchema } from '../config/schema/hotswap.schema.js';
+
+export interface HotSwapArtifact {
+  path: string;
+  hash: string;
+  hashAlgorithm?: HashAlgorithm;
+}
+
+export interface HotSwapManifest {
+  bundleId: string;
+  version: string;
+  artifacts: HotSwapArtifact[];
+  signerId?: string;
+  signature?: string;
+  createdAt?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface HotSwapVerificationResult {
+  ok: boolean;
+  reason: string;
+  signerId?: string;
+}
+
+export declare function fetchHotSwapManifest(url: string): Promise<HotSwapManifest>;
+
+export declare function verifyHotSwapManifest(
+  manifest: HotSwapManifest,
+  policy: HotSwapConfigSchema
+): Promise<HotSwapVerificationResult>;
+
+export declare function serializeHotSwapManifest(manifest: HotSwapManifest): string;

package/src/hotswap/manifest.js

@@ -0,0 +1,114 @@
+
+
+import { log } from '../debug/index.js';
+
+// =============================================================================
+// Fetch + Verification
+// =============================================================================
+
+export async function fetchHotSwapManifest(url) {
+  const response = await fetch(url, { cache: 'no-store' });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch hot-swap manifest: ${response.status}`);
+  }
+  return response.json();
+}
+
+export async function verifyHotSwapManifest(manifest, policy) {
+  if (!policy.enabled) {
+    return { ok: false, reason: 'Hot-swap disabled' };
+  }
+
+  if (!manifest.signature) {
+    if (policy.localOnly && policy.allowUnsignedLocal) {
+      return { ok: true, reason: 'Local-only unsigned manifest accepted' };
+    }
+    return { ok: false, reason: 'Signature required' };
+  }
+
+  if (!manifest.signerId) {
+    return { ok: false, reason: 'Missing signerId' };
+  }
+
+  const signer = policy.trustedSigners.find((entry) => entry.id === manifest.signerId);
+  if (!signer) {
+    return { ok: false, reason: `Signer not trusted: ${manifest.signerId}`, signerId: manifest.signerId };
+  }
+
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    return { ok: false, reason: 'WebCrypto unavailable', signerId: manifest.signerId };
+  }
+
+  try {
+    const payloadBytes = new TextEncoder().encode(serializeHotSwapManifest(manifest));
+    const payload = new Uint8Array(payloadBytes);
+    const signatureBytes = new Uint8Array(decodeBase64ToArrayBuffer(manifest.signature));
+    const key = await importSignerKey(signer);
+    const ok = await subtle.verify(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      key,
+      signatureBytes,
+      payload
+    );
+    return ok
+      ? { ok: true, reason: 'Signature verified', signerId: manifest.signerId }
+      : { ok: false, reason: 'Signature mismatch', signerId: manifest.signerId };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.warn('HotSwap', `Signature verification failed: ${message}`);
+    return { ok: false, reason: 'Signature verification failed', signerId: manifest.signerId };
+  }
+}
+
+export function serializeHotSwapManifest(manifest) {
+  const { signature, ...payload } = manifest;
+  return stableStringify(payload);
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+async function importSignerKey(signer) {
+  return globalThis.crypto.subtle.importKey(
+    'jwk',
+    signer.publicKeyJwk,
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    false,
+    ['verify']
+  );
+}
+
+function decodeBase64ToArrayBuffer(value) {
+  if (typeof atob === 'function') {
+    const raw = atob(value);
+    const bytes = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i += 1) {
+      bytes[i] = raw.charCodeAt(i);
+    }
+    return bytes.buffer;
+  }
+
+  if (typeof Buffer !== 'undefined') {
+    const buffer = Buffer.from(value, 'base64');
+    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+  }
+
+  throw new Error('No base64 decoder available');
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+
+  const record = value;
+  const keys = Object.keys(record).sort();
+  const entries = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+  return `{${entries.join(',')}}`;
+}

package/src/hotswap/runtime.d.ts

@@ -0,0 +1,31 @@
+import type { HotSwapManifest } from './manifest.js';
+import type { HotSwapConfigSchema } from '../config/schema/hotswap.schema.js';
+
+export interface HotSwapRolloutContext {
+  subjectId?: string | null;
+  modelId?: string | null;
+  modelUrl?: string | null;
+  sessionId?: string | null;
+  optInTag?: string | null;
+  forceEnable?: boolean;
+}
+
+export interface HotSwapRolloutDecision {
+  allowed: boolean;
+  mode: string;
+  reason: string;
+  bucket: number | null;
+  threshold: number | null;
+  subjectId: string | null;
+}
+
+export declare function evaluateHotSwapRollout(
+  policy: HotSwapConfigSchema | null | undefined,
+  context?: HotSwapRolloutContext
+): HotSwapRolloutDecision;
+
+export declare function getHotSwapManifest(): HotSwapManifest | null;
+
+export declare function setHotSwapManifest(manifest: HotSwapManifest | null): void;
+
+export declare function getLastHotSwapRolloutDecision(): HotSwapRolloutDecision | null;

package/src/hotswap/runtime.js

@@ -0,0 +1,128 @@
+let activeManifest = null;
+let lastRolloutDecision = null;
+
+function normalizeRolloutPolicy(policy) {
+  const rollout = policy?.rollout && typeof policy.rollout === 'object'
+    ? policy.rollout
+    : {};
+  const rawMode = String(rollout.mode || 'shadow').trim().toLowerCase().replace(/_/g, '-');
+  const mode = rawMode === 'default' || rawMode === 'canary' || rawMode === 'opt-in' || rawMode === 'shadow'
+    ? rawMode
+    : 'shadow';
+  const canaryPercent = Number.isFinite(rollout.canaryPercent)
+    ? Math.min(100, Math.max(0, Number(rollout.canaryPercent)))
+    : 0;
+  const cohortSalt = String(rollout.cohortSalt || 'doppler-hotswap-v1').trim() || 'doppler-hotswap-v1';
+  const optInAllowlist = Array.isArray(rollout.optInAllowlist)
+    ? rollout.optInAllowlist.map((entry) => String(entry || '').trim()).filter(Boolean)
+    : [];
+  return {
+    mode,
+    canaryPercent,
+    cohortSalt,
+    optInAllowlist,
+  };
+}
+
+function hashBucket(value) {
+  const source = String(value || '');
+  let hash = 2166136261;
+  for (let i = 0; i < source.length; i += 1) {
+    hash ^= source.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return Math.abs(hash >>> 0) % 100;
+}
+
+export function evaluateHotSwapRollout(policy = {}, context = {}) {
+  if (policy?.enabled !== true) {
+    const disabled = {
+      allowed: false,
+      mode: 'disabled',
+      reason: 'hotswap_disabled',
+      bucket: null,
+      threshold: null,
+      subjectId: null,
+    };
+    lastRolloutDecision = disabled;
+    return disabled;
+  }
+
+  const rollout = normalizeRolloutPolicy(policy);
+  const subjectId = String(
+    context.subjectId
+    || context.modelId
+    || context.modelUrl
+    || context.sessionId
+    || 'anonymous'
+  );
+  const forced = context.forceEnable === true;
+  const optInTag = String(context.optInTag || '').trim();
+  const bucket = hashBucket(`${rollout.cohortSalt}:${subjectId}`);
+
+  let decision = null;
+  if (forced) {
+    decision = {
+      allowed: true,
+      mode: rollout.mode,
+      reason: 'force_enable',
+      bucket,
+      threshold: rollout.mode === 'canary' ? rollout.canaryPercent : null,
+      subjectId,
+    };
+  } else if (rollout.mode === 'default') {
+    decision = {
+      allowed: true,
+      mode: rollout.mode,
+      reason: 'default_enabled',
+      bucket,
+      threshold: null,
+      subjectId,
+    };
+  } else if (rollout.mode === 'canary') {
+    decision = {
+      allowed: bucket < rollout.canaryPercent,
+      mode: rollout.mode,
+      reason: bucket < rollout.canaryPercent ? 'canary_selected' : 'canary_excluded',
+      bucket,
+      threshold: rollout.canaryPercent,
+      subjectId,
+    };
+  } else if (rollout.mode === 'opt-in') {
+    const allowlisted = rollout.optInAllowlist.includes(subjectId);
+    const tagged = optInTag.length > 0 && rollout.optInAllowlist.includes(optInTag);
+    const allowed = allowlisted === true || tagged === true;
+    decision = {
+      allowed,
+      mode: rollout.mode,
+      reason: allowed ? 'opt_in_selected' : 'opt_in_required',
+      bucket,
+      threshold: null,
+      subjectId,
+    };
+  } else {
+    decision = {
+      allowed: false,
+      mode: rollout.mode,
+      reason: 'shadow_mode',
+      bucket,
+      threshold: null,
+      subjectId,
+    };
+  }
+
+  lastRolloutDecision = decision;
+  return decision;
+}
+
+export function getHotSwapManifest() {
+  return activeManifest;
+}
+
+export function setHotSwapManifest(manifest) {
+  activeManifest = manifest;
+}
+
+export function getLastHotSwapRolloutDecision() {
+  return lastRolloutDecision;
+}