@czap/core 0.1.0

package/src/index.ts

@@ -0,0 +1,274 @@
+/**
+ * `@czap/core` — **LiteShip** primitives for the **CZAP** engine: boundaries,
+ * tokens, styles, themes, signals, and working-deck coordination (compositor,
+ * plan graph, ECS, capsule factory).
+ * @module
+ */
+
+// Brands — sanctioned constructors. The lower-level `brand` factory is
+// intentionally NOT re-exported here; it is the unsafe escape-hatch used
+// by `brands.ts` itself to define the sanctioned set, and exposing it on
+// the public surface would let consumers forge any brand. Code that
+// genuinely needs to mint a new brand should import from `@czap/core/brands`
+// directly and document the use site.
+export { SignalInput, ThresholdValue, StateName, ContentAddress, IntegrityDigest, TokenRef, Millis } from './brands.js';
+export type { HLC as HLCBrand } from './brands.js';
+
+// FNV-1a hash utility
+export { fnv1a, fnv1aBytes } from './fnv.js';
+
+// Canonical CBOR encoder (RFC 8949 §4.2.1) — content-address kernel
+export { CanonicalCbor } from './cbor.js';
+
+// Type utilities
+export type {
+  Prettify,
+  StateUnion,
+  OutputsFor,
+  BoundaryCrossing,
+  EffectValue,
+  EffectError,
+  RequireAtLeastOne,
+  DeepReadonly,
+} from './type-utils.js';
+
+// Tuple utilities
+export { tupleMap } from './tuple.js';
+
+// Boundary. `BoundarySpec` is exported as a value+type pair (see the
+// namespace-object pattern in ADR-0001); consumers who want only the type
+// can `import type { BoundarySpec } from '@czap/core'`.
+export { Boundary, BoundarySpec } from './boundary.js';
+
+// Token
+export { Token } from './token.js';
+export type { TokenCategory } from './token.js';
+
+// Style
+export { Style } from './style.js';
+export type { StyleLayer, ShadowLayer } from './style.js';
+
+// Theme
+export { Theme } from './theme.js';
+
+// Component
+export { Component } from './component.js';
+export type { SlotConfig } from './component.js';
+
+// Signal
+export { Signal } from './signal.js';
+export type { SignalSourceType, SignalSource } from './signal.js';
+
+// Easing
+export { Easing } from './easing.js';
+
+// Animation
+export { Animation } from './animation.js';
+
+// Timeline
+export { Timeline } from './timeline.js';
+
+// Quantizer types
+export type { Quantizer } from './quantizer-types.js';
+
+// Scheduler
+export { Scheduler } from './scheduler.js';
+
+// Compositor
+export { Compositor } from './compositor.js';
+export type { CompositeState, CompositorConfig } from './compositor.js';
+
+// Compositor State Pool
+export { CompositorStatePool } from './compositor-pool.js';
+
+// Speculative Evaluation
+export { SpeculativeEvaluator } from './speculative.js';
+
+// Token Buffer
+export { TokenBuffer } from './token-buffer.js';
+
+// UI Quality
+export { UIQuality } from './ui-quality.js';
+export type { UIQualityTier, MotionTier } from './ui-quality.js';
+
+// Generative UI Frames
+export { GenFrame } from './gen-frame.js';
+export type { UIFrame, FrameType, MorphStrategy, GapStrategy } from './gen-frame.js';
+
+// Video
+export { VideoRenderer } from './video.js';
+export type { VideoConfig, VideoFrameOutput } from './video.js';
+
+// Capture
+export type { CaptureConfig, CaptureFrame, FrameCapture, CaptureResult } from './capture.js';
+
+// Blend
+export { BlendTree } from './blend.js';
+
+// Frame budget
+export { FrameBudget } from './frame-budget.js';
+export type { Priority } from './frame-budget.js';
+
+// Dirty tracking
+export { DirtyFlags } from './dirty.js';
+
+// Protocol
+export type { CellKind, CellMeta, CellEnvelope } from './protocol.js';
+
+// ECS
+export type { Entity, System, DenseSystem, DenseStore } from './ecs.js';
+export { Part, World, EntityId } from './ecs.js';
+
+// Composable
+export { Composable, ComposableWorld } from './composable.js';
+export type { EntityComponents, ComposableEntity, ComposableWorldShape } from './composable.js';
+
+// Cell
+export { Cell } from './cell.js';
+
+// Derived
+export { Derived } from './derived.js';
+
+// Zap
+export { Zap } from './zap.js';
+
+// Store
+export { Store } from './store.js';
+
+// Wire
+export { Wire } from './wire.js';
+
+// Op
+export { Op } from './op.js';
+
+// Cap
+export type { CapLevel, CapSet } from './caps.js';
+export { Cap } from './caps.js';
+
+// HLC
+export { HLC } from './hlc.js';
+
+// VectorClock
+export { VectorClock } from './vector-clock.js';
+
+// TypedRef
+export { TypedRef } from './typed-ref.js';
+
+// Receipt
+export type { ReceiptSubject, ReceiptEnvelope, ChainValidationError } from './receipt.js';
+export { Receipt } from './receipt.js';
+
+// DAG
+export type { DAGNode, ReceiptDAG, MergeResult, ForkViolation } from './dag.js';
+export { DAG } from './dag.js';
+
+// Plan
+export { Plan } from './plan.js';
+export type { OpType, EdgeType } from './plan.js';
+
+// Runtime coordination
+export { RuntimeCoordinator } from './runtime-coordinator.js';
+export type { RuntimePhase, RuntimeCoordinatorConfig } from './runtime-coordinator.js';
+
+// Codec
+export { Codec } from './codec.js';
+// `SchemaError` / `isSchemaError` removed from the main entry — they were
+// orphan re-exports from `effect/Schema` with no consumers in the repo
+// and added implicit coupling to an Effect internal sub-path. Consumers
+// who need them should import directly from `effect/Schema`.
+
+// LiveCell
+export { LiveCell } from './live-cell.js';
+
+// WASM Dispatch
+export { WASMDispatch } from './wasm-dispatch.js';
+export type { WASMKernels, WASMDispatchAPI } from './wasm-dispatch.js';
+export { fallbackKernels } from './wasm-fallback.js';
+
+// AVBridge
+export { AVBridge } from './av-bridge.js';
+
+// AVRenderer
+export { AVRenderer } from './av-renderer.js';
+
+// Defaults (centralized constants)
+export {
+  DEFAULT_TARGET_FPS,
+  MS_PER_SEC,
+  SSE_BUFFER_SIZE,
+  SSE_HEARTBEAT_MS,
+  SSE_RECONNECT_INITIAL_MS,
+  SSE_RECONNECT_MAX_MS,
+  COMPOSITOR_POOL_CAP,
+  DIRTY_FLAGS_MAX,
+  WASM_SCRATCH_BASE,
+  CAPTURE_KEYFRAME_INTERVAL,
+  EASING_SPRING_STEPS,
+  THEME_TRANSITION_DURATION_MS,
+  THEME_TRANSITION_EASING,
+  CANVAS_FALLBACK_WIDTH,
+  CANVAS_FALLBACK_HEIGHT,
+  VIEWPORT,
+} from './defaults.js';
+
+// Validation error
+export { CzapValidationError, isValidationError } from './validation-error.js';
+
+// Diagnostics
+export { Diagnostics } from './diagnostics.js';
+export type { DiagnosticEvent, DiagnosticLevel, DiagnosticPayload, DiagnosticsSink } from './diagnostics.js';
+
+// AddressedDigest + ShipCapsule (ADR-0011)
+// Browser-bundleable: pure type + crypto.subtle hashing. The Node-only
+// release-input manifest helpers (gzip/tar/yaml) live in @czap/cli.
+export { AddressedDigest } from './addressed-digest.js';
+export { ShipCapsule } from './ship-capsule.js';
+
+// Type guards
+import type { Cell as _Cell } from './cell.js';
+import type { Derived as _Derived } from './derived.js';
+import type { Zap as _Zap } from './zap.js';
+import type { Wire as _Wire } from './wire.js';
+
+/** Union of the four reactive primitives the CZAP graph exposes to user code. */
+export type Primitive<T> = _Cell.Shape<T> | _Derived.Shape<T> | _Zap.Shape<T> | _Wire.Shape<T>;
+
+/** Narrow a {@link Primitive} to a {@link Cell}. */
+export const isCell = <T>(p: Primitive<T>): p is _Cell.Shape<T> => p._tag === 'Cell';
+/** Narrow a {@link Primitive} to a {@link Derived}. */
+export const isDerived = <T>(p: Primitive<T>): p is _Derived.Shape<T> => p._tag === 'Derived';
+/** Narrow a {@link Primitive} to a {@link Zap}. */
+export const isZap = <T>(p: Primitive<T>): p is _Zap.Shape<T> => p._tag === 'Zap';
+/** Narrow a {@link Primitive} to a {@link Wire}. */
+export const isWire = <T>(p: Primitive<T>): p is _Wire.Shape<T> => p._tag === 'Wire';
+
+// Config hub
+export { Config, defineConfig } from './config.js';
+export type { PrimitiveKind, PluginConfig as CorePluginConfig, AstroConfig as CoreAstroConfig } from './config.js';
+
+// Capsule factory base types
+export type {
+  AssemblyKind,
+  Site,
+  CapabilityDecl,
+  BudgetDecl,
+  Invariant,
+  AttributionDecl,
+  CapsuleContract,
+} from './capsule.js';
+
+export { TypeValidator } from './capsule.js';
+
+export { defineCapsule, getCapsuleCatalog } from './assembly.js';
+export type { CapsuleDef } from './assembly.js';
+// `resetCapsuleCatalog` is intentionally NOT re-exported here — it mutates
+// global registry state and ships from `@czap/core/testing` only.
+
+// Capsule declarations — concrete instances of the 7-arm factory
+export { boundaryEvaluateCapsule } from './capsules/boundary-evaluate.js';
+export { tokenBufferCapsule } from './capsules/token-buffer.js';
+export { canonicalCborCapsule } from './capsules/canonical-cbor.js';
+
+// Harness lives at `@czap/core/harness` — per-arm test + bench template
+// generators. Not re-exported here so consumers don't pull fast-check and
+// the code-gen surface into every bundle.

package/src/interpolate.ts

@@ -0,0 +1,37 @@
+/**
+ * Value lerping between output states.
+ *
+ * Linearly interpolates all numeric properties of a record
+ * from one state to another, controlled by an eased progress value.
+ *
+ * @module
+ */
+
+/**
+ * Interpolate between two numeric records using an eased value [0..1].
+ * Returns a new record with each property lerped: from[k] + (to[k] - from[k]) * eased.
+ */
+export function interpolate<T extends Record<string, number>>(
+  from: T,
+  to: T,
+  eased: number,
+  defaults?: Partial<Record<string, number>>,
+): T {
+  const result: Record<string, number> = {};
+  for (const [key, a] of Object.entries(from)) {
+    const b = to[key] ?? a;
+    result[key] = a + (b - a) * eased;
+  }
+  // Second pass: keys only in `to` (interpolate from implicit 0)
+  for (const [key, b] of Object.entries(to)) {
+    if (key in result) {
+      continue;
+    }
+
+    const base = defaults?.[key] ?? 0;
+    result[key] = base + (b - base) * eased;
+  }
+  // `result` has every key present in `from`/`to`, both of which are T. The
+  // output is structurally a T but TS can't infer that through Object.entries.
+  return result as unknown as T;
+}

package/src/live-cell.ts

@@ -0,0 +1,199 @@
+/**
+ * `LiveCell<K, T>` — bridge between protocol envelope and reactive runtime.
+ *
+ * A LiveCell is a Cell that also carries a CellEnvelope, tracking
+ * its kind, content address, metadata (HLC timestamps, version),
+ * and boundary crossings.
+ *
+ * @module
+ */
+
+import type { Scope } from 'effect';
+import { Effect, Stream, PubSub, Ref } from 'effect';
+import { Cell } from './cell.js';
+import type { CellKind, CellMeta, CellEnvelope } from './protocol.js';
+import type { ContentAddress, HLC as HLCBrand } from './brands.js';
+import { ContentAddress as mkContentAddress, StateName as mkStateName } from './brands.js';
+import type { BoundaryCrossing } from './type-utils.js';
+import { HLC } from './hlc.js';
+import { canonicalize, hash } from './typed-ref.js';
+import { Boundary } from './boundary.js';
+
+interface LiveCellShape<K extends CellKind, T> extends Omit<Cell.Shape<T>, '_tag'> {
+  readonly _tag: 'LiveCell';
+  readonly envelope: Effect.Effect<CellEnvelope<K, T>>;
+  readonly crossings: Stream.Stream<BoundaryCrossing<string>>;
+  readonly kind: K;
+  publishCrossing(crossing: BoundaryCrossing<string>): Effect.Effect<void>;
+}
+
+function _make<K extends CellKind, T>(kind: K, initial: T): Effect.Effect<LiveCellShape<K, T>, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const cell = yield* Cell.make(initial);
+    const clockRef = yield* HLC.makeClock(`live-cell-${kind}`);
+    const createdHlc = yield* HLC.tick(clockRef);
+    const versionRef = yield* Ref.make(1);
+    const crossingPub = yield* PubSub.unbounded<BoundaryCrossing<string>>();
+    const createdRef = yield* Ref.make<HLCBrand>(createdHlc);
+    const updatedRef = yield* Ref.make<HLCBrand>(createdHlc);
+
+    const computeId = (value: T): Effect.Effect<ContentAddress> =>
+      Effect.gen(function* () {
+        const h = yield* hash(canonicalize({ kind, value }));
+        return mkContentAddress(h);
+      });
+
+    const initialId = yield* computeId(initial);
+    const idRef = yield* Ref.make<ContentAddress>(initialId);
+
+    const recordMutation = (value: T): Effect.Effect<void> =>
+      Effect.gen(function* () {
+        const hlc = yield* HLC.tick(clockRef);
+        yield* Ref.set(updatedRef, hlc);
+        yield* Ref.update(versionRef, (v) => v + 1);
+        const newId = yield* computeId(value);
+        yield* Ref.set(idRef, newId);
+      });
+
+    const liveCell: LiveCellShape<K, T> = {
+      _tag: 'LiveCell' as const,
+      ref: cell.ref,
+      changes: cell.changes,
+      get: cell.get,
+      set: (value: T) =>
+        Effect.gen(function* () {
+          yield* cell.set(value);
+          yield* recordMutation(value);
+        }),
+      update: (f: (current: T) => T) =>
+        Effect.gen(function* () {
+          const current = yield* cell.get;
+          const next = f(current);
+          yield* cell.set(next);
+          yield* recordMutation(next);
+        }),
+      kind,
+      crossings: Stream.fromPubSub(crossingPub),
+      publishCrossing: (crossing: BoundaryCrossing<string>) => PubSub.publish(crossingPub, crossing),
+      envelope: Effect.gen(function* () {
+        const value = yield* cell.get;
+        const created = yield* Ref.get(createdRef);
+        const updated = yield* Ref.get(updatedRef);
+        const version = yield* Ref.get(versionRef);
+        const id = yield* Ref.get(idRef);
+
+        const meta: CellMeta = { created, updated, version };
+        const envelope: CellEnvelope<K, T> = { kind, id, meta, value };
+        return envelope;
+      }),
+    };
+
+    return liveCell;
+  });
+}
+
+/**
+ * Create a boundary-kind LiveCell that automatically publishes crossings
+ * when the numeric value transitions between boundary states.
+ */
+function _makeBoundary<I extends string, S extends readonly [string, ...string[]]>(
+  boundary: Boundary.Shape<I, S>,
+  initial: number,
+): Effect.Effect<LiveCellShape<'boundary', number>, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const cell = yield* Cell.make(initial);
+    const clockRef = yield* HLC.makeClock(`live-cell-boundary`);
+    const createdHlc = yield* HLC.tick(clockRef);
+    const versionRef = yield* Ref.make(1);
+    const crossingPub = yield* PubSub.unbounded<BoundaryCrossing<string>>();
+    const createdRef = yield* Ref.make<HLCBrand>(createdHlc);
+    const updatedRef = yield* Ref.make<HLCBrand>(createdHlc);
+    const kind = 'boundary' as const;
+
+    const computeId = (value: number): Effect.Effect<ContentAddress> =>
+      Effect.gen(function* () {
+        const h = yield* hash(canonicalize({ kind, value }));
+        return mkContentAddress(h);
+      });
+
+    const initialId = yield* computeId(initial);
+    const idRef = yield* Ref.make<ContentAddress>(initialId);
+
+    const initialState: string = Boundary.evaluate(boundary, initial);
+    const prevStateRef = yield* Ref.make(initialState);
+
+    const recordMutation = (value: number): Effect.Effect<void> =>
+      Effect.gen(function* () {
+        const hlc = yield* HLC.tick(clockRef);
+        yield* Ref.set(updatedRef, hlc);
+        yield* Ref.update(versionRef, (v) => v + 1);
+        const newId = yield* computeId(value);
+        yield* Ref.set(idRef, newId);
+
+        const prevState = yield* Ref.get(prevStateRef);
+        const nextState: string = Boundary.evaluateWithHysteresis(boundary, value, prevState);
+        if (nextState !== prevState) {
+          yield* Ref.set(prevStateRef, nextState);
+          yield* PubSub.publish(crossingPub, {
+            from: mkStateName(prevState),
+            to: mkStateName(nextState),
+            timestamp: hlc,
+            value,
+          });
+        }
+      });
+
+    const liveCell: LiveCellShape<'boundary', number> = {
+      _tag: 'LiveCell' as const,
+      ref: cell.ref,
+      changes: cell.changes,
+      get: cell.get,
+      set: (value: number) =>
+        Effect.gen(function* () {
+          yield* cell.set(value);
+          yield* recordMutation(value);
+        }),
+      update: (f: (current: number) => number) =>
+        Effect.gen(function* () {
+          const current = yield* cell.get;
+          const next = f(current);
+          yield* cell.set(next);
+          yield* recordMutation(next);
+        }),
+      kind,
+      crossings: Stream.fromPubSub(crossingPub),
+      publishCrossing: (crossing: BoundaryCrossing<string>) => PubSub.publish(crossingPub, crossing),
+      envelope: Effect.gen(function* () {
+        const value = yield* cell.get;
+        const created = yield* Ref.get(createdRef);
+        const updated = yield* Ref.get(updatedRef);
+        const version = yield* Ref.get(versionRef);
+        const id = yield* Ref.get(idRef);
+
+        const meta: CellMeta = { created, updated, version };
+        const envelope: CellEnvelope<'boundary', number> = { kind, id, meta, value };
+        return envelope;
+      }),
+    };
+
+    return liveCell;
+  });
+}
+
+/**
+ * LiveCell — bridge between the {@link Cell} reactive graph and the wire
+ * protocol. A `LiveCell` wraps a `Cell` with a typed {@link CellEnvelope} —
+ * kind, content address, HLC, boundary crossings — so primitives can travel
+ * between peers as self-describing messages.
+ */
+export const LiveCell = {
+  /** Wrap an arbitrary value in a {@link LiveCell} with freshly minted identity + HLC. */
+  make: _make,
+  /** Specialized factory for boundary crossings so the envelope captures crossing metadata. */
+  makeBoundary: _makeBoundary,
+};
+
+export declare namespace LiveCell {
+  /** Structural shape of a {@link LiveCell} parameterized by cell kind `K` and value type `T`. */
+  export type Shape<K extends CellKind, T> = LiveCellShape<K, T>;
+}