@czap/core 0.1.0

package/src/op.ts

@@ -0,0 +1,233 @@
+/**
+ * `Op<A, E, R>` — `Effect.Effect` wrapper with named factories.
+ *
+ * @module
+ */
+
+import type { Scope, Result } from 'effect';
+import { Effect, Schedule, Duration } from 'effect';
+import type { Millis } from './brands.js';
+
+interface OpShape<A, E = never, R = never> {
+  readonly _tag: 'Op';
+  readonly effect: Effect.Effect<A, E, R>;
+  run(): Effect.Effect<A, E, R | Scope.Scope>;
+  map<B>(f: (a: A) => B): OpShape<B, E, R>;
+  flatMap<B, E2, R2>(f: (a: A) => OpShape<B, E2, R2>): OpShape<B, E | E2, R | R2>;
+}
+
+type OpValue<T extends OpShape<unknown, unknown, unknown>> = T extends OpShape<infer A, unknown, unknown> ? A : never;
+type OpError<T extends OpShape<unknown, unknown, unknown>> = T extends OpShape<unknown, infer E, unknown> ? E : never;
+type OpRequirement<T extends OpShape<unknown, unknown, unknown>> =
+  T extends OpShape<unknown, unknown, infer R> ? R : never;
+type OpValues<T extends readonly OpShape<unknown, unknown, unknown>[]> = { [K in keyof T]: OpValue<T[K]> };
+type SettledOpValues<T extends readonly OpShape<unknown, unknown, unknown>[]> = {
+  [K in keyof T]: Result.Result<OpValue<T[K]>, OpError<T[K]>>;
+};
+
+/**
+ * Wraps an Effect into an Op, providing `.map()` and `.flatMap()` chaining.
+ *
+ * @example
+ * ```ts
+ * const op = Op.make(Effect.succeed(42));
+ * const doubled = op.map(n => n * 2);
+ * const result = Effect.runSync(doubled.run()); // 84
+ * ```
+ */
+const _make = <A, E = never, R = never>(effect: Effect.Effect<A, E, R>): OpShape<A, E, R> => ({
+  _tag: 'Op' as const,
+  effect,
+  run: () => effect,
+  map: <B>(fn: (a: A) => B): OpShape<B, E, R> => _make(Effect.map(effect, fn)),
+  flatMap: <B, E2, R2>(fn: (a: A) => OpShape<B, E2, R2>): OpShape<B, E | E2, R | R2> =>
+    _make(Effect.flatMap(effect, (a) => fn(a).effect)),
+});
+
+/**
+ * Creates an Op from a Promise-returning function, catching errors as `Error`.
+ *
+ * @example
+ * ```ts
+ * const op = Op.fromPromise(() => fetch('/api/data').then(r => r.json()));
+ * const result = await Effect.runPromise(op.run());
+ * console.log(result); // parsed JSON response
+ * ```
+ */
+const _fromPromise = <A>(f: () => Promise<A>): OpShape<A, Error> =>
+  _make(
+    Effect.tryPromise({
+      try: f,
+      catch: (error) => (error instanceof Error ? error : new Error(String(error))),
+    }),
+  );
+
+/**
+ * Creates an Op that immediately succeeds with the given value.
+ *
+ * @example
+ * ```ts
+ * const op = Op.succeed({ name: 'dark', contrast: 0.9 });
+ * const result = Effect.runSync(op.run()); // { name: 'dark', contrast: 0.9 }
+ * ```
+ */
+const _succeed = <A>(value: A): OpShape<A> => _make(Effect.succeed(value));
+
+/**
+ * Creates an Op that immediately fails with the given error.
+ *
+ * @example
+ * ```ts
+ * const op = Op.fail(new Error('GPU not available'));
+ * // Effect.runSync(op.run()) would throw
+ * ```
+ */
+const _fail = <E>(error: E): OpShape<never, E> => _make(Effect.fail(error));
+
+/**
+ * Runs all Ops concurrently and returns their results as a tuple.
+ * Fails if any Op fails.
+ *
+ * @example
+ * ```ts
+ * const a = Op.succeed(10);
+ * const b = Op.succeed('hello');
+ * const combined = Op.all([a, b] as const);
+ * const [num, str] = Effect.runSync(combined.run()); // [10, 'hello']
+ * ```
+ */
+// Effect.all's overloads infer tuple results only when the input shape itself is tuple-typed.
+// `tasks.map(...)` widens to unknown[], so we contain one cast into a typed wrapper and
+// apply it at the boundary where the tuple→Op product is materialized.
+const _all = <T extends readonly OpShape<unknown, unknown, unknown>[]>(
+  tasks: T,
+): OpShape<OpValues<T>, OpError<T[number]>, OpRequirement<T[number]>> => {
+  const effects = tasks.map((task) => task.effect);
+  const combined = Effect.all(effects, { concurrency: 'unbounded' }) as unknown as Effect.Effect<
+    OpValues<T>,
+    OpError<T[number]>,
+    OpRequirement<T[number]>
+  >;
+  return _make(combined);
+};
+
+/**
+ * Runs all Ops concurrently and returns a Result for each, never failing.
+ * Each result is either a success or a failure.
+ *
+ * @example
+ * ```ts
+ * const a = Op.succeed(1);
+ * const b = Op.fail(new Error('oops'));
+ * const settled = Op.allSettled([a, b] as const);
+ * const results = Effect.runSync(settled.run());
+ * // results[0] is Result.success(1), results[1] is Result.failure(Error)
+ * ```
+ */
+// Mirrors _all: one boundary cast from unknown[] back to the tuple-projected product.
+const _allSettled = <T extends readonly OpShape<unknown, unknown, unknown>[]>(
+  tasks: T,
+): OpShape<SettledOpValues<T>, never, OpRequirement<T[number]>> => {
+  const resultEffects = tasks.map((task) => Effect.result(task.effect));
+  const combined = Effect.all(resultEffects, { concurrency: 'unbounded' }) as unknown as Effect.Effect<
+    SettledOpValues<T>,
+    never,
+    OpRequirement<T[number]>
+  >;
+  return _make(combined);
+};
+
+/**
+ * Races multiple Ops concurrently, returning the first to complete.
+ * Fails with an error if the array is empty.
+ *
+ * @example
+ * ```ts
+ * const fast = Op.succeed('fast');
+ * const slow = Op.fromPromise(() => new Promise(r => setTimeout(() => r('slow'), 100)));
+ * const winner = Op.race([fast, slow]);
+ * const result = Effect.runSync(winner.run()); // 'fast'
+ * ```
+ */
+const _race = <A, E, R>(tasks: ReadonlyArray<OpShape<A, E, R>>): OpShape<A, E | Error, R> => {
+  if (tasks.length === 0) {
+    return _fail(new Error('Op.race: empty array'));
+  }
+  if (tasks.length === 1) {
+    return tasks[0]!;
+  }
+  const effects = tasks.map((task) => task.effect);
+  const raced = effects.reduce((acc, effect) => Effect.race(acc, effect));
+  return _make(raced);
+};
+
+/**
+ * Retries a failing Op with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * const flaky = Op.fromPromise(() => fetch('/unstable-api').then(r => r.json()));
+ * const resilient = Op.retry(flaky, { times: 3, delay: Millis(200), factor: 2 });
+ * const result = await Effect.runPromise(resilient.run());
+ * ```
+ */
+const _retry = <A, E, R>(
+  task: OpShape<A, E, R>,
+  options: { times: number; delay?: Millis; factor?: number },
+): OpShape<A, E, R> => {
+  const delay = options.delay ?? 100;
+  const factor = options.factor ?? 2;
+
+  const schedule = Schedule.exponential(Duration.millis(delay), factor).pipe(
+    Schedule.both(Schedule.recurs(options.times)),
+  );
+
+  return _make(Effect.retry(task.effect, schedule));
+};
+
+/**
+ * Wraps an Op with a timeout, failing with an Error if it exceeds the given duration.
+ *
+ * @example
+ * ```ts
+ * const slow = Op.fromPromise(() => new Promise(r => setTimeout(() => r('done'), 5000)));
+ * const bounded = Op.timeout(slow, Millis(1000));
+ * // Will fail with Error('Op timed out after 1000ms') if not resolved in time
+ * ```
+ */
+const _timeout = <A, E, R>(task: OpShape<A, E, R>, ms: Millis): OpShape<A, E | Error, R> =>
+  _make(
+    Effect.timeout(task.effect, Duration.millis(ms)).pipe(
+      Effect.catchTag('TimeoutError', () => Effect.fail(new Error(`Op timed out after ${ms}ms`))),
+    ),
+  );
+
+/**
+ * Op -- Effect.Effect wrapper providing named factories and combinators
+ * for async operations with retry, timeout, race, and parallel execution.
+ *
+ * @example
+ * ```ts
+ * const op = Op.succeed(42).map(n => n * 2);
+ * const result = Effect.runSync(op.run()); // 84
+ *
+ * const tasks = Op.all([Op.succeed(1), Op.succeed(2)] as const);
+ * const [a, b] = Effect.runSync(tasks.run()); // [1, 2]
+ * ```
+ */
+export const Op = {
+  make: _make,
+  fromPromise: _fromPromise,
+  succeed: _succeed,
+  fail: _fail,
+  all: _all,
+  allSettled: _allSettled,
+  race: _race,
+  retry: _retry,
+  timeout: _timeout,
+};
+
+export declare namespace Op {
+  /** Structural shape of an {@link Op}: a thin alias over `Effect.Effect<A, E, R>` produced by the `Op.*` factories. */
+  export type Shape<A, E = never, R = never> = OpShape<A, E, R>;
+}

package/src/plan.ts

@@ -0,0 +1,317 @@
+/**
+ * Plan -- plan IR builder for universal execution DAG.
+ *
+ * @module
+ */
+
+/**
+ * Discriminated union describing the kind of work a `PlanStep` performs.
+ *
+ * `pure` and `effect` name an executable function; `spawn` references a child
+ * fiber/worker keyed by `key`; `domain` dispatches to an external domain's
+ * named operation; `choice` marks a branch point; `noop` is an explicit
+ * placeholder.
+ */
+export type OpType =
+  | { readonly type: 'pure'; readonly fn?: string }
+  | { readonly type: 'effect'; readonly fn?: string }
+  | { readonly type: 'spawn'; readonly key: string; readonly spec: Record<string, unknown> }
+  | { readonly type: 'domain'; readonly domain: string; readonly op: string }
+  | { readonly type: 'choice'; readonly condition: unknown }
+  | { readonly type: 'noop' };
+
+/**
+ * Edge flavor in a plan DAG: sequential (`seq`), parallel (`par`), or the two
+ * branches of a `choice` step (`choice_then` / `choice_else`).
+ */
+export type EdgeType = 'seq' | 'par' | 'choice_then' | 'choice_else';
+
+/** A single node in a {@link PlanIR}: an identifier, a display name, and its {@link OpType}. */
+export interface PlanStep {
+  readonly id: string;
+  readonly name: string;
+  readonly opType: OpType;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** A directed edge between two {@link PlanStep}s, tagged by {@link EdgeType}. */
+export interface PlanEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly type: EdgeType;
+}
+
+/** Intermediate representation of a plan: named steps plus directed edges. */
+export interface PlanIR {
+  readonly name: string;
+  readonly steps: readonly PlanStep[];
+  readonly edges: readonly PlanEdge[];
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Structural failure from {@link Plan.validate}: either a cycle or an edge pointing at a missing step. */
+export type PlanValidationError =
+  | { readonly type: 'cycle'; readonly message: string; readonly stepIds?: readonly string[] }
+  | { readonly type: 'missing_step'; readonly message: string; readonly stepIds?: readonly string[] };
+
+/** Result of {@link Plan.validate}: either the validated plan or a list of errors. */
+export type PlanValidationResult =
+  | { readonly ok: true; readonly plan: PlanIR }
+  | { readonly ok: false; readonly errors: readonly PlanValidationError[] };
+
+/**
+ * Result of {@link Plan.topoSort}: the sorted step IDs, optionally accompanied by
+ * the IDs that participated in a detected cycle.
+ */
+export type TopoSortResult =
+  | { readonly sorted: readonly string[]; readonly cycle?: undefined }
+  | { readonly sorted: readonly string[]; readonly cycle: readonly string[] };
+
+interface PlanBuilder {
+  step(name: string, opType: OpType, metadata?: Record<string, unknown>): PlanBuilder;
+  seq(fromId: string, toId: string): PlanBuilder;
+  par(fromId: string, toId: string): PlanBuilder;
+  choice(fromId: string, thenId: string, elseId: string): PlanBuilder;
+  build(): PlanIR;
+}
+
+class PlanBuilderImpl implements PlanBuilder {
+  private steps: PlanStep[] = [];
+  private edges: PlanEdge[] = [];
+
+  constructor(private readonly planName: string) {}
+
+  step(name: string, opType: OpType, metadata?: Record<string, unknown>): PlanBuilder {
+    const id = `step-${this.steps.length + 1}`;
+    this.steps.push({ id, name, opType, metadata });
+    return this;
+  }
+
+  seq(fromId: string, toId: string): PlanBuilder {
+    this.edges.push({ from: fromId, to: toId, type: 'seq' });
+    return this;
+  }
+
+  par(fromId: string, toId: string): PlanBuilder {
+    this.edges.push({ from: fromId, to: toId, type: 'par' });
+    return this;
+  }
+
+  choice(fromId: string, thenId: string, elseId: string): PlanBuilder {
+    this.edges.push({ from: fromId, to: thenId, type: 'choice_then' });
+    this.edges.push({ from: fromId, to: elseId, type: 'choice_else' });
+    return this;
+  }
+
+  build(): PlanIR {
+    return {
+      name: this.planName,
+      steps: [...this.steps],
+      edges: [...this.edges],
+    };
+  }
+}
+
+/**
+ * Create a new PlanBuilder with the given plan name.
+ *
+ * Returns a fluent builder that supports chaining `.step()`, `.seq()`,
+ * `.par()`, and `.choice()` calls. Call `.build()` to produce the PlanIR.
+ *
+ * @example
+ * ```ts
+ * const plan = Plan.make('my-pipeline')
+ *   .step('fetch', { type: 'effect' })
+ *   .step('transform', { type: 'pure' })
+ *   .seq('step-1', 'step-2')
+ *   .build();
+ * // plan.name === 'my-pipeline'
+ * // plan.steps.length === 2
+ * // plan.edges.length === 1
+ * ```
+ */
+function _make(name: string): PlanBuilder {
+  return new PlanBuilderImpl(name);
+}
+
+function hasCycle(planIR: PlanIR): boolean {
+  const visited = new Set<string>();
+  const recStack = new Set<string>();
+  const adjList = new Map<string, string[]>();
+
+  for (const step of planIR.steps) {
+    adjList.set(step.id, []);
+  }
+
+  for (const edge of planIR.edges) {
+    adjList.get(edge.from)?.push(edge.to);
+  }
+
+  function dfs(node: string): boolean {
+    visited.add(node);
+    recStack.add(node);
+    for (const neighbor of adjList.get(node) ?? []) {
+      if (!visited.has(neighbor)) {
+        if (dfs(neighbor)) return true;
+      } else if (recStack.has(neighbor)) {
+        return true;
+      }
+    }
+    recStack.delete(node);
+    return false;
+  }
+
+  for (const step of planIR.steps) {
+    if (!visited.has(step.id) && dfs(step.id)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Validate a PlanIR for structural correctness.
+ *
+ * Checks that all edges reference existing steps and that the graph is acyclic.
+ * Returns `{ ok: true, plan }` on success or `{ ok: false, errors }` with
+ * detailed validation errors.
+ *
+ * @example
+ * ```ts
+ * const plan = Plan.make('test').step('a', { type: 'noop' }).build();
+ * const result = Plan.validate(plan);
+ * // result.ok === true
+ * // result.plan === plan
+ * ```
+ */
+function _validate(planIR: PlanIR): PlanValidationResult {
+  const errors: PlanValidationError[] = [];
+  const stepIds = new Set(planIR.steps.map((s) => s.id));
+
+  for (const edge of planIR.edges) {
+    if (!stepIds.has(edge.from)) {
+      errors.push({
+        type: 'missing_step',
+        message: `Edge references unknown step: ${edge.from}`,
+        stepIds: [edge.from],
+      });
+    }
+    if (!stepIds.has(edge.to)) {
+      errors.push({
+        type: 'missing_step',
+        message: `Edge references unknown step: ${edge.to}`,
+        stepIds: [edge.to],
+      });
+    }
+  }
+
+  if (hasCycle(planIR)) {
+    errors.push({ type: 'cycle', message: 'Plan contains a cycle' });
+  }
+
+  return errors.length === 0 ? { ok: true, plan: planIR } : { ok: false, errors };
+}
+
+/**
+ * Topologically sort the steps of a PlanIR using Kahn's algorithm.
+ *
+ * Returns `{ sorted }` on success. If a cycle exists, returns
+ * `{ sorted, cycle }` where `cycle` lists the step IDs involved.
+ *
+ * @example
+ * ```ts
+ * const plan = Plan.make('pipeline')
+ *   .step('a', { type: 'pure' })
+ *   .step('b', { type: 'pure' })
+ *   .seq('step-1', 'step-2')
+ *   .build();
+ * const result = Plan.topoSort(plan);
+ * // result.sorted === ['step-1', 'step-2']
+ * ```
+ */
+function _topoSort(planIR: PlanIR): TopoSortResult {
+  const adjList = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+
+  for (const step of planIR.steps) {
+    adjList.set(step.id, []);
+    inDegree.set(step.id, 0);
+  }
+
+  for (const edge of planIR.edges) {
+    adjList.get(edge.from)?.push(edge.to);
+    inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+  }
+
+  const queue: string[] = [];
+  const result: string[] = [];
+
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id);
+  }
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    result.push(current);
+    for (const neighbor of adjList.get(current) ?? []) {
+      const newDegree = inDegree.get(neighbor)! - 1;
+      inDegree.set(neighbor, newDegree);
+      if (newDegree === 0) queue.push(neighbor);
+    }
+  }
+
+  if (result.length !== planIR.steps.length) {
+    const resultSet = new Set(result);
+    const cycleNodes = planIR.steps.filter((s) => !resultSet.has(s.id)).map((s) => s.id);
+    return { sorted: result, cycle: cycleNodes };
+  }
+
+  return { sorted: result };
+}
+
+/**
+ * Plan namespace -- plan IR builder for universal execution DAG.
+ *
+ * Build, validate, and topologically sort execution plans. Plans model
+ * computation graphs with sequential, parallel, and conditional edges.
+ *
+ * @example
+ * ```ts
+ * import { Plan } from '@czap/core';
+ *
+ * const plan = Plan.make('render-pipeline')
+ *   .step('load', { type: 'effect' })
+ *   .step('compile', { type: 'pure' })
+ *   .step('emit', { type: 'effect' })
+ *   .seq('step-1', 'step-2')
+ *   .seq('step-2', 'step-3')
+ *   .build();
+ * const valid = Plan.validate(plan);
+ * const order = Plan.topoSort(plan);
+ * // order.sorted === ['step-1', 'step-2', 'step-3']
+ * ```
+ */
+export const Plan = {
+  /** Start a new fluent {@link Plan.Builder} with the given display name. */
+  make: _make,
+  /** Check that every edge references a known step and that the graph is acyclic. */
+  validate: _validate,
+  /** Kahn's-algorithm topological sort; surfaces cycle participants if the plan is not a DAG. */
+  topoSort: _topoSort,
+};
+
+export declare namespace Plan {
+  /** Alias for `PlanIR`. */
+  export type IR = PlanIR;
+  /** Alias for `PlanStep`. */
+  export type Step = PlanStep;
+  /** Alias for `PlanEdge`. */
+  export type Edge = PlanEdge;
+  /** Alias for `PlanValidationError`. */
+  export type ValidationError = PlanValidationError;
+  /** Alias for `PlanValidationResult`. */
+  export type ValidationResult = PlanValidationResult;
+  /** Alias for `TopoSortResult`. */
+  export type TopoSort = TopoSortResult;
+  /** Fluent builder interface returned by `Plan.make`. */
+  export type Builder = PlanBuilder;
+}

package/src/protocol.ts

@@ -0,0 +1,49 @@
+/**
+ * Protocol types -- CellEnvelope, CellKind, CellMeta.
+ *
+ * These types form the wire-level protocol for cells in the czap system.
+ * Every cell has a kind, content address, metadata, and value.
+ *
+ * @module
+ */
+
+import type { ContentAddress, HLC } from './brands.js';
+
+/**
+ * Discriminator tagging what a {@link CellEnvelope} carries — a boundary, a
+ * discrete state, a target output (CSS/GLSL/WGSL/ARIA/AI), or one of the
+ * other reactive shapes produced along the pipeline.
+ */
+export type CellKind =
+  | 'boundary'
+  | 'state'
+  | 'output'
+  | 'signal'
+  | 'transition'
+  | 'timeline'
+  | 'compositor'
+  | 'blend'
+  | 'css'
+  | 'glsl'
+  | 'wgsl'
+  | 'aria'
+  | 'ai';
+
+/** Protocol metadata attached to every {@link CellEnvelope}: HLC timestamps + monotonic version counter. */
+export interface CellMeta {
+  readonly created: HLC;
+  readonly updated: HLC;
+  readonly version: number;
+}
+
+/**
+ * Wire-level envelope for a cell value: tagged by {@link CellKind}, identified
+ * by its content address, stamped with {@link CellMeta}, carrying the typed
+ * payload in `value`.
+ */
+export interface CellEnvelope<K extends CellKind = CellKind, T = unknown> {
+  readonly kind: K;
+  readonly id: ContentAddress;
+  readonly meta: CellMeta;
+  readonly value: T;
+}

package/src/quantizer-types.ts

@@ -0,0 +1,29 @@
+/**
+ * Quantizer interface -- the base contract for quantizer implementations.
+ *
+ * The canonical implementation lives in `@czap/quantizer` (`Q.from()` builder API).
+ *
+ * @module
+ */
+
+import type { Effect, Stream } from 'effect';
+import type { Boundary } from './boundary.js';
+import type { StateUnion, BoundaryCrossing } from './type-utils.js';
+
+/**
+ * Quantizer contract — the live evaluator that binds a {@link Boundary} to a signal source.
+ *
+ * A quantizer holds a boundary definition plus the reactive machinery to observe
+ * its current state and emit crossings when the underlying signal moves between
+ * bands. The concrete implementation is produced by `@czap/quantizer`'s `Q.from()`
+ * builder; consumers interact only via this structural interface.
+ */
+export interface Quantizer<B extends Boundary.Shape = Boundary.Shape> {
+  readonly _tag: 'Quantizer';
+  readonly boundary: B;
+  readonly state: Effect.Effect<StateUnion<B>>;
+  /** Synchronous state accessor for hot paths (avoids Effect overhead). */
+  readonly stateSync?: () => StateUnion<B>;
+  readonly changes: Stream.Stream<BoundaryCrossing<StateUnion<B> & string>>;
+  evaluate(value: number): StateUnion<B>;
+}