@czap/core 0.1.0

package/src/ui-quality.ts

@@ -0,0 +1,105 @@
+/**
+ * UIQuality -- maps buffer occupancy + device capability to UI complexity tier.
+ *
+ * Same pattern as video ABR (Adaptive Bitrate). Composite signal from
+ * buffer occupancy and device tier determines rendering fidelity.
+ *
+ * @module
+ */
+
+import type { MotionTier as _MotionTier } from '@czap/_spine';
+import { Boundary } from './boundary.js';
+
+/**
+ * Motion tier — re-anchored from `@czap/_spine` (the canonical declaration
+ * per ADR-0010). The ladder runs from lowest capability (`none`, forced by
+ * `prefers-reduced-motion: reduce` regardless of GPU tier) to highest
+ * (`compute`, which unlocks the Rust/WASM kernels).
+ */
+export type MotionTier = _MotionTier;
+
+/**
+ * Coarse UI-complexity ladder, in increasing fidelity: `skeleton` (placeholder
+ * blocks only) up through `rich` (full interactive styled content).
+ */
+export type UIQualityTier = 'skeleton' | 'text-only' | 'styled' | 'interactive' | 'rich';
+
+/** {@link Boundary.Shape} instantiation used by {@link UIQuality} — input = `buffer-occupancy`, states = the {@link UIQualityTier} ladder. */
+export type UIQualityBoundary = Boundary.Shape<
+  'buffer-occupancy',
+  readonly ['skeleton', 'text-only', 'styled', 'interactive', 'rich']
+>;
+
+/**
+ * Pre-built boundary for UI quality based on buffer occupancy signal.
+ * Thresholds tuned for streaming UI: aggressive degradation when buffer low.
+ */
+const uiQualityBoundary: UIQualityBoundary = Boundary.make({
+  input: 'buffer-occupancy',
+  at: [
+    [0.0, 'skeleton'],
+    [0.15, 'text-only'],
+    [0.35, 'styled'],
+    [0.6, 'interactive'],
+    [0.85, 'rich'],
+  ] as const,
+  hysteresis: 0.1,
+});
+
+/**
+ * Motion tier to normalized device capability score (0-1).
+ */
+const DEVICE_CAPABILITY_SCORES: Record<MotionTier, number> = {
+  none: 0.0,
+  transitions: 0.25,
+  animations: 0.5,
+  physics: 0.75,
+  compute: 1.0,
+};
+
+interface UIQualityEvaluatorShape {
+  evaluate(bufferOccupancy: number, deviceTier?: MotionTier): UIQualityTier;
+  readonly boundary: UIQualityBoundary;
+}
+
+function _make(): UIQualityEvaluatorShape {
+  let previousTier: UIQualityTier = 'skeleton';
+
+  return {
+    evaluate(bufferOccupancy: number, deviceTier?: MotionTier): UIQualityTier {
+      // Composite signal: buffer occupancy weighted more heavily
+      const deviceScore = deviceTier ? DEVICE_CAPABILITY_SCORES[deviceTier] : 0.5;
+      const composite = bufferOccupancy * 0.7 + deviceScore * 0.3;
+
+      // Boundary.evaluateWithHysteresis now returns the exact state literal union ('skeleton' | ... | 'rich')
+      // because uiQualityBoundary's S parameter is narrowed via `as const`.
+      const result = Boundary.evaluateWithHysteresis(uiQualityBoundary, composite, previousTier);
+
+      previousTier = result;
+      return result;
+    },
+
+    boundary: uiQualityBoundary,
+  };
+}
+
+/**
+ * UIQuality — adaptive-bitrate-style UI fidelity gate.
+ *
+ * Combines buffer occupancy (how far ahead the generator is) and device
+ * {@link MotionTier} into a composite score and maps it via {@link Boundary}
+ * with hysteresis to a {@link UIQualityTier}.
+ */
+export const UIQuality = {
+  /** Build a stateful evaluator that remembers the previous tier for hysteresis. */
+  make: _make,
+  /** The pre-built boundary — exposed so callers can compile it to CSS/GLSL directly. */
+  boundary: uiQualityBoundary,
+};
+
+export declare namespace UIQuality {
+  /** Structural shape of a UIQuality evaluator. */
+  export type Shape = UIQualityEvaluatorShape;
+  /** Alias for {@link UIQualityTier}. */
+  export type Tier = UIQualityTier;
+}

package/src/validation-error.ts

@@ -0,0 +1,34 @@
+/**
+ * Structured validation error for factory/constructor failures.
+ *
+ * Thrown (not Effect.fail'd) because all factory functions are synchronous.
+ * Callers can catch and `instanceof CzapValidationError` to distinguish
+ * czap validation failures from other errors.
+ *
+ * @module
+ */
+
+/**
+ * Structured validation error thrown by czap factory/constructor functions.
+ *
+ * Carries a `module` identifier (e.g. `'Boundary.make'`) and a human-readable
+ * `detail` message. Synchronous factories throw this directly so callers can
+ * `catch` and branch via {@link isValidationError} without Effect plumbing.
+ */
+export class CzapValidationError extends Error {
+  readonly _tag = 'CzapValidationError' as const;
+  readonly module: string;
+  readonly detail: string;
+
+  constructor(module: string, detail: string) {
+    super(`${module}: ${detail}`);
+    this.name = 'CzapValidationError';
+    this.module = module;
+    this.detail = detail;
+  }
+}
+
+/** Type guard for CzapValidationError */
+export function isValidationError(error: unknown): error is CzapValidationError {
+  return error instanceof CzapValidationError;
+}

package/src/vector-clock.ts

@@ -0,0 +1,111 @@
+/**
+ * VectorClock -- causality tracking for distributed systems.
+ *
+ * @module
+ */
+
+interface VectorClockShape {
+  readonly _tag: 'VectorClock';
+  readonly entries: ReadonlyMap<string, number>;
+}
+
+const _make = (): VectorClockShape => ({
+  _tag: 'VectorClock',
+  entries: new Map(),
+});
+
+const _from = (entries: Record<string, number>): VectorClockShape => ({
+  _tag: 'VectorClock',
+  entries: new Map(Object.entries(entries)),
+});
+
+const _get = (vc: VectorClockShape, peerId: string): number => vc.entries.get(peerId) ?? 0;
+
+const _tick = (vc: VectorClockShape, peerId: string): VectorClockShape => {
+  const newEntries = new Map(vc.entries);
+  newEntries.set(peerId, _get(vc, peerId) + 1);
+  return { _tag: 'VectorClock', entries: newEntries };
+};
+
+const _merge = (a: VectorClockShape, b: VectorClockShape): VectorClockShape => {
+  const newEntries = new Map(a.entries);
+  for (const [peerId, counter] of b.entries) {
+    const existing = newEntries.get(peerId) ?? 0;
+    newEntries.set(peerId, Math.max(existing, counter));
+  }
+  return { _tag: 'VectorClock', entries: newEntries };
+};
+
+const _happensBefore = (a: VectorClockShape, b: VectorClockShape): boolean => {
+  const allPeers = new Set([...a.entries.keys(), ...b.entries.keys()]);
+  let hasStrictlyLess = false;
+
+  for (const peerId of allPeers) {
+    const aValue = _get(a, peerId);
+    const bValue = _get(b, peerId);
+    if (aValue > bValue) return false;
+    if (aValue < bValue) hasStrictlyLess = true;
+  }
+
+  return hasStrictlyLess;
+};
+
+const _equals = (a: VectorClockShape, b: VectorClockShape): boolean => {
+  const allPeers = new Set([...a.entries.keys(), ...b.entries.keys()]);
+  for (const peerId of allPeers) {
+    if (_get(a, peerId) !== _get(b, peerId)) return false;
+  }
+  return true;
+};
+
+const _concurrent = (a: VectorClockShape, b: VectorClockShape): boolean =>
+  !_happensBefore(a, b) && !_happensBefore(b, a) && !_equals(a, b);
+
+const _compare = (a: VectorClockShape, b: VectorClockShape): -1 | 0 | 1 => {
+  if (_happensBefore(a, b)) return -1;
+  if (_happensBefore(b, a)) return 1;
+  return 0;
+};
+
+const _toObject = (vc: VectorClockShape): Record<string, number> => Object.fromEntries(vc.entries);
+
+const _peers = (vc: VectorClockShape): string[] => [...vc.entries.keys()];
+
+const _size = (vc: VectorClockShape): number => vc.entries.size;
+
+/**
+ * VectorClock — per-peer counter algebra for causal ordering.
+ * Pairs with {@link HLC} when you need exact happens-before rather than HLC's
+ * hybrid ordering.
+ */
+export const VectorClock = {
+  /** Build an empty vector clock. */
+  make: _make,
+  /** Build a vector clock from an existing `Record<peer, counter>`. */
+  from: _from,
+  /** Read the counter for a single peer. */
+  get: _get,
+  /** Increment the counter for the given peer, returning a new clock. */
+  tick: _tick,
+  /** Pointwise-max merge of two clocks. */
+  merge: _merge,
+  /** `true` iff `a` strictly happens-before `b`. */
+  happensBefore: _happensBefore,
+  /** `true` iff `a` and `b` are causally concurrent. */
+  concurrent: _concurrent,
+  /** Exact structural equality. */
+  equals: _equals,
+  /** `-1 | 0 | 1` comparator suitable for `sort`; `0` when concurrent. */
+  compare: _compare,
+  /** Convert to a plain `Record<peer, counter>`. */
+  toObject: _toObject,
+  /** List peers known to the clock. */
+  peers: _peers,
+  /** Number of peers. */
+  size: _size,
+};
+
+export declare namespace VectorClock {
+  /** Structural shape of a vector clock: a `Map<peer, counter>` wrapper. */
+  export type Shape = VectorClockShape;
+}

package/src/video.ts

@@ -0,0 +1,106 @@
+/**
+ * VideoRenderer -- fixed-step frame generator for deterministic video rendering.
+ *
+ * Same compositor, same state pipeline -- different clock. The VideoRenderer
+ * drives a FixedStepScheduler at target fps, producing VideoFrameOutput
+ * per frame with the full CompositeState snapshot.
+ *
+ * @module
+ */
+
+import type { Scheduler } from './scheduler.js';
+import { Scheduler as SchedulerImpl } from './scheduler.js';
+import type { CompositeState, Compositor } from './compositor.js';
+import type { Signal } from './signal.js';
+import type { Millis } from './brands.js';
+import { Effect } from 'effect';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Configuration for a {@link VideoRenderer}: resolution, target fps, and total duration. */
+export interface VideoConfig {
+  readonly fps: number;
+  readonly width: number;
+  readonly height: number;
+  readonly durationMs: Millis;
+}
+
+/**
+ * Single frame yielded by `VideoRenderer.frames()`: frame index, timestamp,
+ * normalized progress, and the {@link CompositeState} snapshot captured at that tick.
+ */
+export interface VideoFrameOutput {
+  readonly frame: number;
+  readonly timestamp: number;
+  readonly progress: number;
+  readonly state: CompositeState;
+}
+
+interface VideoRendererShape {
+  readonly config: VideoConfig;
+  readonly totalFrames: number;
+  readonly scheduler: Scheduler.FixedStep;
+  frames(): AsyncGenerator<VideoFrameOutput>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a video renderer that produces deterministic frames from a Compositor.
+ *
+ * Each call to `frames()` returns an async generator yielding one
+ * `VideoFrameOutput` per frame at the configured fps/duration.
+ *
+ * When a `signal` is provided it is seeked to each frame's timestamp before
+ * the compositor evaluates, so quantizers that read from that signal advance
+ * deterministically with the render clock.
+ */
+function _make(
+  config: VideoConfig,
+  compositor: Compositor.Shape,
+  signal?: Signal.Controllable<number>,
+): VideoRendererShape {
+  const totalFrames = Math.ceil((config.durationMs / 1000) * config.fps);
+  const scheduler = SchedulerImpl.fixedStep(config.fps);
+
+  return {
+    config,
+    totalFrames,
+    scheduler,
+    async *frames(): AsyncGenerator<VideoFrameOutput> {
+      for (let i = 0; i < totalFrames; i++) {
+        scheduler.step();
+        const timestamp = (i * 1000) / config.fps;
+        if (signal) {
+          Effect.runSync(signal.seek(timestamp));
+        }
+        const state = Effect.runSync(compositor.compute());
+        yield {
+          frame: i,
+          timestamp,
+          progress: totalFrames > 1 ? i / (totalFrames - 1) : 1,
+          state,
+        };
+      }
+    },
+  };
+}
+
+/**
+ * VideoRenderer — fixed-step frame generator for deterministic offline rendering.
+ * Drives a {@link Compositor} at the configured fps and optionally seeks a
+ * controllable time {@link Signal} so every frame is reproducible.
+ */
+export const VideoRenderer = {
+  /** Create a renderer bound to the given compositor and optional seekable time signal. */
+  make: _make,
+};
+
+export declare namespace VideoRenderer {
+  /** Structural shape of a renderer instance returned by {@link VideoRenderer.make}. */
+  export type Shape = VideoRendererShape;
+}

package/src/wasm-dispatch.ts

@@ -0,0 +1,300 @@
+/**
+ * WASM escape hatch -- capability detection, module loading, and dispatch.
+ *
+ * Detects WebAssembly availability, loads the czap-compute WASM module,
+ * and provides a unified kernel interface that transparently falls back
+ * to pure TypeScript implementations when WASM is unavailable.
+ *
+ * Usage:
+ *   const kernels = WASMDispatch.kernels();        // TS fallbacks
+ *   await WASMDispatch.load(wasmUrl);               // upgrade to WASM
+ *   const kernels2 = WASMDispatch.kernels();        // now WASM-backed
+ *
+ * @module
+ */
+
+import { fallbackKernels } from './wasm-fallback.js';
+import { WASM_SCRATCH_BASE } from './defaults.js';
+
+// ---------------------------------------------------------------------------
+// Public kernel interface
+// ---------------------------------------------------------------------------
+
+/** Kernel functions available from both WASM and TS fallback. */
+export interface WASMKernels {
+  /**
+   * Sample a spring easing at `samples` evenly-spaced points in [0, 1].
+   * Returns Float32Array of length `samples + 1`.
+   */
+  springCurve(stiffness: number, damping: number, mass: number, samples: number): Float32Array;
+
+  /**
+   * Batch boundary evaluation. For each value, returns the index of the
+   * highest threshold where `value >= threshold`.
+   * Thresholds must be sorted ascending.
+   */
+  batchBoundaryEval(thresholds: Float64Array, values: Float64Array): Uint32Array;
+
+  /**
+   * Normalize weights in-place so positive values sum to 1.0.
+   * Negative weights clamped to 0. Returns the (modified) input array.
+   */
+  blendNormalize(weights: Float32Array): Float32Array;
+}
+
+// ---------------------------------------------------------------------------
+// WASM instance state
+// ---------------------------------------------------------------------------
+
+/** Raw WASM export signatures matching C-ABI from czap-compute. */
+interface WASMExports {
+  memory: WebAssembly.Memory;
+  spring_curve(stiffness: number, damping: number, mass: number, samples: number): number;
+  batch_boundary_eval(thresholds_ptr: number, thresholds_len: number, values_ptr: number, values_len: number): number;
+  blend_normalize(weights_ptr: number, len: number): void;
+}
+
+/**
+ * Runtime-verified cast from WebAssembly's opaque exports to the typed interface.
+ *
+ * `WebAssembly.Instance.exports` is structurally `Record<string, unknown>` — functions,
+ * memories, tables, and globals are all opaque at the type level. This helper
+ * asserts the expected functions are present as callable values and that the
+ * memory export is a WebAssembly.Memory instance, then narrows. If any required
+ * export is missing or the wrong shape, it throws — making the cast runtime-safe.
+ *
+ * This is a sanctioned cast containment point (cf. tuple.ts, cell.ts, boundary.ts,
+ * typed-ref.ts).
+ */
+const validateWASMExports = (exports: WebAssembly.Exports): WASMExports => {
+  const requiredFunctions = ['spring_curve', 'batch_boundary_eval', 'blend_normalize'] as const;
+  for (const name of requiredFunctions) {
+    if (typeof exports[name] !== 'function') {
+      throw new Error(
+        `WASM module missing required export: "${name}". Available exports: [${Object.keys(exports).join(', ')}]`,
+      );
+    }
+  }
+  const mem = exports['memory'];
+  const isMemoryShape =
+    mem !== null &&
+    typeof mem === 'object' &&
+    'buffer' in mem &&
+    Reflect.get(mem, 'buffer') instanceof ArrayBuffer;
+  /* v8 ignore next 5 — sanctioned cast containment: the czap-compute WASM module always
+     exports `memory` as a WebAssembly.Memory (whose `.buffer` is an ArrayBuffer); this
+     guard exists only so the cast to WASMExports stays runtime-safe if a caller ever
+     supplies a drift/tampered module. Cannot be reached by valid instantiate output. */
+  if (!isMemoryShape) {
+    throw new Error(
+      `WASM module missing required memory export. Available exports: [${Object.keys(exports).join(', ')}]`,
+    );
+  }
+  return exports as unknown as WASMExports;
+};
+
+/** Loaded WASM module state. */
+let wasmInstance: WASMExports | null = null;
+
+type WASMAvailabilityProbe =
+  | { readonly status: 'ok'; readonly available: boolean }
+  | { readonly status: 'unavailable' }
+  | { readonly status: 'error'; readonly error: unknown };
+
+function wasmAvailable(available: boolean): WASMAvailabilityProbe {
+  return { status: 'ok', available };
+}
+
+function wasmUnavailable(): WASMAvailabilityProbe {
+  return { status: 'unavailable' };
+}
+
+function wasmProbeError(error: unknown): WASMAvailabilityProbe {
+  return { status: 'error', error };
+}
+
+function probeWASMAvailability(): WASMAvailabilityProbe {
+  try {
+    if (typeof WebAssembly === 'undefined') {
+      return wasmUnavailable();
+    }
+
+    return wasmAvailable(typeof WebAssembly.instantiate === 'function' && typeof WebAssembly.Module === 'function');
+  } catch (error) {
+    return wasmProbeError(error);
+  }
+}
+
+function isWASMAvailable(probe: WASMAvailabilityProbe): boolean {
+  return probe.status === 'ok' ? probe.available : false;
+}
+
+// ---------------------------------------------------------------------------
+// WASM-backed kernel wrappers
+// ---------------------------------------------------------------------------
+
+function createWASMKernels(wasm: WASMExports): WASMKernels {
+  return {
+    springCurve(stiffness: number, damping: number, mass: number, samples: number): Float32Array {
+      const count = Math.min(Math.max(0, samples | 0), 255);
+      const ptr = wasm.spring_curve(stiffness, damping, mass, count);
+      const view = new Float32Array(wasm.memory.buffer, ptr, count + 1);
+      return new Float32Array(view);
+    },
+
+    batchBoundaryEval(thresholds: Float64Array, values: Float64Array): Uint32Array {
+      const tLen = thresholds.length;
+      const vLen = values.length;
+
+      const SCRATCH_BASE = WASM_SCRATCH_BASE;
+      const thresholdsOffset = SCRATCH_BASE;
+      const valuesOffset = thresholdsOffset + tLen * 4;
+
+      const needed = valuesOffset + vLen * 4;
+      const currentSize = wasm.memory.buffer.byteLength;
+      if (needed > currentSize) {
+        const pages = Math.ceil((needed - currentSize) / 65536);
+        wasm.memory.grow(pages);
+      }
+
+      const threshF32 = new Float32Array(wasm.memory.buffer, thresholdsOffset, tLen);
+      for (let i = 0; i < tLen; i++) {
+        threshF32[i] = thresholds[i]!;
+      }
+
+      const valF32 = new Float32Array(wasm.memory.buffer, valuesOffset, vLen);
+      for (let i = 0; i < vLen; i++) {
+        valF32[i] = values[i]!;
+      }
+
+      const resultPtr = wasm.batch_boundary_eval(thresholdsOffset, tLen, valuesOffset, vLen);
+      const view = new Uint32Array(wasm.memory.buffer, resultPtr, vLen);
+      return new Uint32Array(view);
+    },
+
+    blendNormalize(weights: Float32Array): Float32Array {
+      const len = weights.length;
+      if (len === 0) return weights;
+
+      const SCRATCH_BASE = WASM_SCRATCH_BASE;
+      const needed = SCRATCH_BASE + len * 4;
+      const currentSize = wasm.memory.buffer.byteLength;
+      if (needed > currentSize) {
+        const pages = Math.ceil((needed - currentSize) / 65536);
+        wasm.memory.grow(pages);
+      }
+
+      const wasmWeights = new Float32Array(wasm.memory.buffer, SCRATCH_BASE, len);
+      wasmWeights.set(weights);
+
+      wasm.blend_normalize(SCRATCH_BASE, len);
+
+      const result = new Float32Array(wasm.memory.buffer, SCRATCH_BASE, len);
+      weights.set(result);
+      return weights;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Public API of the {@link WASMDispatch} singleton: probe for WebAssembly,
+ * asynchronously load the Rust compute module, and hand back either WASM or
+ * {@link fallbackKernels} via {@link WASMDispatchAPI.kernels}.
+ */
+export interface WASMDispatchAPI {
+  detect(): boolean;
+  load(wasmUrl: string | ArrayBuffer): Promise<WASMKernels>;
+  kernels(): WASMKernels;
+  isLoaded(): boolean;
+  unload(): void;
+}
+
+let wasmKernels: WASMKernels | null = null;
+let loadingPromise: Promise<WASMKernels> | null = null;
+let loadingToken: object | null = null;
+let loadSession = 0;
+
+/**
+ * WASMDispatch — singleton that wires the Rust compute crate (spring, boundary,
+ * blend kernels) into the runtime, falling back to {@link fallbackKernels}
+ * when WebAssembly is unavailable or the module fails to load.
+ */
+export const WASMDispatch: WASMDispatchAPI = {
+  detect(): boolean {
+    return isWASMAvailable(probeWASMAvailability());
+  },
+
+  load(wasmUrl: string | ArrayBuffer): Promise<WASMKernels> {
+    if (!WASMDispatch.detect()) {
+      return Promise.reject(new Error('WebAssembly is not available in this environment'));
+    }
+
+    if (loadingPromise !== null) {
+      return loadingPromise;
+    }
+
+    const currentSession = ++loadSession;
+    const currentToken = {};
+    loadingToken = currentToken;
+    const promise = (async () => {
+      try {
+        let source: BufferSource;
+        if (typeof wasmUrl === 'string') {
+          const response = await fetch(wasmUrl);
+          if (!response.ok) {
+            throw new Error(`Failed to fetch WASM module: ${response.status} ${response.statusText}`);
+          }
+          source = await response.arrayBuffer();
+        } else {
+          source = wasmUrl;
+        }
+
+        const { instance } = await WebAssembly.instantiate(source, {
+          env: {},
+        });
+
+        wasmInstance = validateWASMExports(instance.exports);
+
+        wasmKernels = createWASMKernels(wasmInstance);
+
+        // If unload() ran while we were awaiting fetch/instantiate, it will
+        // bump the session and clear the just-installed WASM state.
+        if (loadSession !== currentSession) {
+          wasmInstance = null;
+          wasmKernels = null;
+          return fallbackKernels;
+        }
+
+        return wasmKernels;
+      } finally {
+        if (loadingToken === currentToken) {
+          loadingPromise = null;
+          loadingToken = null;
+        }
+      }
+    })();
+
+    loadingPromise = promise;
+    return promise;
+  },
+
+  kernels(): WASMKernels {
+    return wasmKernels ?? fallbackKernels;
+  },
+
+  isLoaded(): boolean {
+    return wasmKernels !== null;
+  },
+
+  unload(): void {
+    loadSession += 1;
+    wasmInstance = null;
+    wasmKernels = null;
+    loadingPromise = null;
+    loadingToken = null;
+  },
+};