@czap/core 0.1.0

package/dist/live-cell.js

@@ -0,0 +1,154 @@
+/**
+ * `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 { Effect, Stream, PubSub, Ref } from 'effect';
+import { Cell } from './cell.js';
+import { ContentAddress as mkContentAddress, StateName as mkStateName } from './brands.js';
+import { HLC } from './hlc.js';
+import { canonicalize, hash } from './typed-ref.js';
+import { Boundary } from './boundary.js';
+function _make(kind, initial) {
+    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();
+        const createdRef = yield* Ref.make(createdHlc);
+        const updatedRef = yield* Ref.make(createdHlc);
+        const computeId = (value) => Effect.gen(function* () {
+            const h = yield* hash(canonicalize({ kind, value }));
+            return mkContentAddress(h);
+        });
+        const initialId = yield* computeId(initial);
+        const idRef = yield* Ref.make(initialId);
+        const recordMutation = (value) => 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 = {
+            _tag: 'LiveCell',
+            ref: cell.ref,
+            changes: cell.changes,
+            get: cell.get,
+            set: (value) => Effect.gen(function* () {
+                yield* cell.set(value);
+                yield* recordMutation(value);
+            }),
+            update: (f) => 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) => 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 = { created, updated, version };
+                const envelope = { 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(boundary, initial) {
+    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();
+        const createdRef = yield* Ref.make(createdHlc);
+        const updatedRef = yield* Ref.make(createdHlc);
+        const kind = 'boundary';
+        const computeId = (value) => Effect.gen(function* () {
+            const h = yield* hash(canonicalize({ kind, value }));
+            return mkContentAddress(h);
+        });
+        const initialId = yield* computeId(initial);
+        const idRef = yield* Ref.make(initialId);
+        const initialState = Boundary.evaluate(boundary, initial);
+        const prevStateRef = yield* Ref.make(initialState);
+        const recordMutation = (value) => 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 = 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 = {
+            _tag: 'LiveCell',
+            ref: cell.ref,
+            changes: cell.changes,
+            get: cell.get,
+            set: (value) => Effect.gen(function* () {
+                yield* cell.set(value);
+                yield* recordMutation(value);
+            }),
+            update: (f) => 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) => 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 = { created, updated, version };
+                const envelope = { 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,
+};
+//# sourceMappingURL=live-cell.js.map

package/dist/live-cell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-cell.js","sourceRoot":"","sources":["../src/live-cell.ts"],"names":[],"mappings":"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"}

package/dist/op.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `Op<A, E, R>` — `Effect.Effect` wrapper with named factories.
+ *
+ * @module
+ */
+import type { Scope, Result } from 'effect';
+import { Effect } 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]>>;
+};
+/**
+ * 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 declare const Op: {
+    make: <A, E = never, R = never>(effect: Effect.Effect<A, E, R>) => OpShape<A, E, R>;
+    fromPromise: <A>(f: () => Promise<A>) => OpShape<A, Error>;
+    succeed: <A>(value: A) => OpShape<A>;
+    fail: <E>(error: E) => OpShape<never, E>;
+    all: <T extends readonly OpShape<unknown, unknown, unknown>[]>(tasks: T) => OpShape<OpValues<T>, OpError<T[number]>, OpRequirement<T[number]>>;
+    allSettled: <T extends readonly OpShape<unknown, unknown, unknown>[]>(tasks: T) => OpShape<SettledOpValues<T>, never, OpRequirement<T[number]>>;
+    race: <A, E, R>(tasks: ReadonlyArray<OpShape<A, E, R>>) => OpShape<A, E | Error, R>;
+    retry: <A, E, R>(task: OpShape<A, E, R>, options: {
+        times: number;
+        delay?: Millis;
+        factor?: number;
+    }) => OpShape<A, E, R>;
+    timeout: <A, E, R>(task: OpShape<A, E, R>, ms: Millis) => OpShape<A, E | Error, R>;
+};
+export declare namespace Op {
+    /** Structural shape of an {@link Op}: a thin alias over `Effect.Effect<A, E, R>` produced by the `Op.*` factories. */
+    type Shape<A, E = never, R = never> = OpShape<A, E, R>;
+}
+export {};
+//# sourceMappingURL=op.d.ts.map

package/dist/op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.d.ts","sourceRoot":"","sources":["../src/op.ts"],"names":[],"mappings":"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"}

package/dist/op.js

@@ -0,0 +1,171 @@
+/**
+ * `Op<A, E, R>` — `Effect.Effect` wrapper with named factories.
+ *
+ * @module
+ */
+import { Effect, Schedule, Duration } from 'effect';
+/**
+ * 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 = (effect) => ({
+    _tag: 'Op',
+    effect,
+    run: () => effect,
+    map: (fn) => _make(Effect.map(effect, fn)),
+    flatMap: (fn) => _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 = (f) => _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 = (value) => _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 = (error) => _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 = (tasks) => {
+    const effects = tasks.map((task) => task.effect);
+    const combined = Effect.all(effects, { concurrency: 'unbounded' });
+    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 = (tasks) => {
+    const resultEffects = tasks.map((task) => Effect.result(task.effect));
+    const combined = Effect.all(resultEffects, { concurrency: 'unbounded' });
+    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 = (tasks) => {
+    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 = (task, options) => {
+    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 = (task, ms) => _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,
+};
+//# sourceMappingURL=op.js.map

package/dist/op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.js","sourceRoot":"","sources":["../src/op.ts"],"names":[],"mappings":"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"}

package/dist/plan.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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;
+}
+/**
+ * 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
+ * ```
+ */
+declare function _make(name: string): PlanBuilder;
+/**
+ * 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
+ * ```
+ */
+declare function _validate(planIR: PlanIR): PlanValidationResult;
+/**
+ * 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']
+ * ```
+ */
+declare function _topoSort(planIR: PlanIR): TopoSortResult;
+/**
+ * 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 declare const Plan: {
+    /** Start a new fluent {@link Plan.Builder} with the given display name. */
+    make: typeof _make;
+    /** Check that every edge references a known step and that the graph is acyclic. */
+    validate: typeof _validate;
+    /** Kahn's-algorithm topological sort; surfaces cycle participants if the plan is not a DAG. */
+    topoSort: typeof _topoSort;
+};
+export declare namespace Plan {
+    /** Alias for `PlanIR`. */
+    type IR = PlanIR;
+    /** Alias for `PlanStep`. */
+    type Step = PlanStep;
+    /** Alias for `PlanEdge`. */
+    type Edge = PlanEdge;
+    /** Alias for `PlanValidationError`. */
+    type ValidationError = PlanValidationError;
+    /** Alias for `PlanValidationResult`. */
+    type ValidationResult = PlanValidationResult;
+    /** Alias for `TopoSortResult`. */
+    type TopoSort = TopoSortResult;
+    /** Fluent builder interface returned by `Plan.make`. */
+    type Builder = PlanBuilder;
+}
+export {};
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}