@asciiz/atoolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asciizzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ReadMe.md

@@ -0,0 +1,198 @@
+# Atoolkit: Modular Computational Toolkit & Hardware Execution Framework
+
+A collection of zero-dependency TypeScript modules designed for simulation, numerical evaluation, entity management, and WebGPU hardware execution.
+
+All modules share common engineering invariants: zero-allocation calling conventions on hot paths, contiguous typed array storage, deterministic execution plans, and dual-tier hardware transparency.
+
+---
+
+## 1. Package Architecture
+
+| Package | Role | Core Data Structures | Performance & Memory Invariants | Documentation |
+| :--- | :--- | :--- | :--- | :--- |
+| **[`aecs`](./aecs/ReadMe.md)** | Entity Component System | `Entity`, `EntityPool`, `ComponentSet<T>`, `FloatSet`, `QueryBuilder`, `query2`, `query3` | Contiguous packed dense arrays; generational slot recycling; cardinality-driven smallest-set iteration. | [aecs ReadMe](./aecs/ReadMe.md) |
+| **[`alm`](./alm/ReadMe.md)** | 3D Linear Algebra & Spatial Math | `Vec2`, `Vec3`, `Vec4`, `Quat`, `Mat3`, `Mat4`, `Ray`, `Plane`, `AABB`, `Frustum` | Direct subclassing of native `Float32Array`; in-place fluent operations; out-parameter zero-allocation conventions. | [alm ReadMe](./alm/ReadMe.md) |
+| **[`atempo`](./atempo/ReadMe.md)** | Temporal Orchestration & Cadence | `Track`, `FloatTrack`, `Vec3Track`, `Curve`, `Clip`, `Cadence`, `FixedCadence`, `Spring`, `Phase`, `Metronome` | Contiguous double-precision timestamps; cached O(1) interval lookup; closed-form 2nd-order analytical spring solvers. | [atempo ReadMe](./atempo/ReadMe.md) |
+| **[`acircuit`](./acircuit/ReadMe.md)** | Directed Computation Circuit | `Socket`, `Wire`, `Chip`, `Circuit`, `Subcircuit` | Kahn topological ordering; execution plan caching (`_cachedPlan`); 1-to-1 input enforcement; 1-to-N output fan-out. | [acircuit ReadMe](./acircuit/ReadMe.md) |
+| **[`awgpu`](./awgpu/ReadMe.md)** | Six-Tier WebGPU Hardware Engine | `Device`, `Buffer`, `BufferPool`, `Texture`, `Sampler`, `StreamSet`, `Target`, `BindLayout`, `BindTable`, `RasterPipeline`, `ComputePipeline`, `PipelineCache`, `RenderPassNode`, `ComputePassNode`, `PassSequence`, `PassGraph` | Zero-allocation render pass descriptors; transient buffer pooling; automated vertex strides; 8-slot bind group filtering; DAG dead pass culling. | [awgpu ReadMe](./awgpu/ReadMe.md) |
+| **[`adiag`](./adiag/ReadMe.md)** | Diagnostic Telemetry Bus | `Bus`, `Result`, causal chain tracers | Fixed-capacity circular ring buffer (default 1000 records); non-throwing diagnostics; pointer-based causal error chains (`ref`). | [adiag ReadMe](./adiag/ReadMe.md) |
+| **[`awasm`](./awasm/ReadMe.md)** | WebAssembly Computational Runtime & Memory Coordinator | `WasmMemory`, `LinearArena`, `BlockPool`, `MemoryView`, `StructLayout`, `Slice`, `StringBuffer`, `ModuleInspector`, `HostBridge`, `ModuleLoader`, `WasmInstance`, `SharedMemory`, `AtomicQueue`, `WorkerPool` | Monotonic bump allocation; detachment-resilient typed views; 16-byte SIMD alignment; intrusive slab recycling; lock-free atomic queues. | [awasm ReadMe](./awasm/ReadMe.md) |
+
+---
+
+## 2. Subsystem Specifications
+
+### 2.1 aecs: Entity Component System
+
+High-performance, sets-first ECS decoupled from rigid scene graphs.
+
+- **Entity Allocation**: `Entity` packs a 20-bit slot index and a 12-bit generation counter into a single integer. `EntityPool` manages issuance, generational validation, and slot recycling via an internal free-list array.
+- **Dense Storage Primitives**:
+  - `ComponentSet<T>`: Contiguous sparse-dense storage for JavaScript objects, state tags, and reference payloads.
+  - `FloatSet`: Contiguous packed `Float32Array` storage for high-frequency numeric vectors and matrices, eliminating object reference overhead.
+- **Cardinality Joins**: `QueryBuilder`, `query2()`, and `query3()` identify the smallest active component set and iterate only across that driver set, testing presence in secondary sets in O(1) time.
+
+### 2.2 alm: 3D Linear Algebra & Spatial Primitives
+
+High-performance 3D mathematics built directly on native typed arrays.
+
+- **Storage Layout**: Every mathematical primitive (`Vec2`, `Vec3`, `Vec4`, `Quat`, `Mat3`, `Mat4`) subclasses `Float32Array` directly. Slices and views write directly into WebGPU buffers (`device.queue.writeBuffer`) with zero serialization or memory copying.
+- **Dual Calling Convention**:
+  - Fluent in-place methods (`v.add(b)`) mutate instances and return `this`.
+  - Static procedural methods (`Mat4.mul(a, b, out)`) accept destination `out` buffers to guarantee zero heap allocations in hot animation loops.
+- **Spatial Structures**: Provides analytical intersection testing, frustum-bounding sphere containment, ray-plane casting, and bounding-box containment via `Ray`, `Plane`, `AABB`, and `Frustum`.
+
+### 2.3 atempo: Temporal Orchestration & Cadence
+
+Time-shaping functions and sequence evaluation primitives decoupled from concrete data interpolation.
+
+- **Sequence Evaluation**: `Track<T, TOut>` manages chronological keyframe sequences, locates active interval spans via cached index pointers (falling back to O(log N) binary search on non-linear seeks), and shapes progress using unary transfer functions (`Curve`).
+- **Composite Timelines**: `Clip` evaluates heterogeneous tracks simultaneously across a unified temporal coordinate space.
+- **Analytical Harmonic Dynamics**: `Spring` implements a closed-form analytical second-order damped harmonic oscillator, evaluating exact displacement and velocity in continuous time without numerical Euler integration errors.
+- **Cadence & Timesteps**: `Cadence` computes frame-rate independent exponential half-life decay. `FixedCadence` accumulates elapsed frame time and produces deterministic fixed-timestep simulation steps.
+
+### 2.4 acircuit: Directed Computation Circuit
+
+Value computation graph featuring static topology validation and plan caching.
+
+- **Endpoints & Connections**: `Socket` declares input or output endpoints with optional data type constraints and requirement tags. `Wire` defines directed connections linking an output socket to an input socket. Input sockets strictly enforce 1-to-1 connections; output sockets support 1-to-N fan-out.
+- **Computation Units**: `Chip` represents a stateless computational node that declares socket schemas and evaluates input records.
+- **Graph Ownership**: `Circuit` validates connections against cycles and missing required inputs, derives topological evaluation sequences via Kahn's algorithm, and caches the resulting execution plan (`_cachedPlan`).
+- **Composite Encapsulation**: `Subcircuit` wraps an entire circuit inside a single composite chip, mapping boundary sockets and enabling hierarchical composition.
+
+### 2.5 awgpu: Six-Tier WebGPU Hardware Engine
+
+Domain-agnostic WebGPU execution engine built across six distinct compositional levels:
+
+- **Level 0 (Hardware Foundation)**: `Device` acquires adapters, logical devices, and queue handles. Exposes hardware telemetry (`limits`, `features`, `lost`) and attaches error hooks (`onError`, `onDeviceLost`).
+- **Level 1 (Managed Memory)**: `Buffer` encapsulates sized allocations and uniform alignment. `BufferPool` recycles transient buffers across frames via power-of-two size bucketing. `Texture` handles 256-byte aligned row stride calculations (`write2D`) and external image copy (`copyExternalImage`). `Sampler` configures filtering and shadow comparison modes.
+- **Level 2 (Data Structures)**: `StreamSet` groups planar or interleaved vertex attributes and index streams, automatically deriving 4-byte aligned vertex buffer layouts. `Target` manages swapchain backbuffers, offscreen multi-render-targets (MRT), MSAA resolution, and cached render pass descriptors. `SwapBuffer` manages ping-pong buffer pointers in O(1) time.
+- **Level 3 (Resource Binding)**: `BindLayoutBuilder` constructs `GPUBindGroupLayout` descriptors with fluent method chaining. `BindTable` normalizes raw or wrapped resources into native binding descriptors. `BindTableCache` automatically deduplicates identical bind groups via deterministic composite hashing.
+- **Level 4 (Hardware Pipelines)**: `RasterPipeline` and `ComputePipeline` compile shader modules with synchronous and asynchronous factory methods. `PipelineCache` provides deterministic 32-bit FNV-1a descriptor hashing and cached retrieval.
+- **Level 5 (Command Sequencing & DAG)**: `RenderPassNode` and `ComputePassNode` record commands while filtering redundant driver state changes (tracking 8 bind group slots, vertex buffers, and index buffers). `PassGraph` schedules passes via Kahn topological sort, resolving read/write hazards and eliminating dead passes via reverse reachability from side-effect roots.
+
+### 2.6 adiag: Diagnostic Telemetry Bus
+
+Structured diagnostics and causal error tracing without cross-boundary thrown exceptions.
+
+- **Structured Records**: `Result` captures category types (`"ok"`, `"err"`, `"warn"`, `"info"`), machine-readable codes, templated messages, arbitrary key-value payloads, and parent error references (`ref`).
+- **Circular History**: `Bus` logs diagnostic records into a pre-allocated circular ring buffer (default 1000 entries) in O(1) time, overwriting oldest records when capacity is reached.
+- **Causal Traversal**: Tracing utilities traverse parent `ref` pointers to extract chronological root cause failure chains across asynchronous subsystem boundaries.
+
+### 2.7 awasm: WebAssembly Computational Runtime & Linear Memory Coordinator
+
+Low-level WebAssembly execution runtime, linear memory arena coordinator, binary inspector, and multi-threaded worker dispatch framework.
+
+- **Memory Subsystem**: `WasmMemory` tracks page growth and notifies listeners when native buffers detach. `LinearArena` provides O(1) bump allocations with 4/8/16-byte alignment and watermark rewinding. `BlockPool` manages intrusive free-list slab recycling. `MemoryView` exposes detachment-resilient typed array views.
+- **ABI Subsystem**: `StructLayout` computes member byte offsets and stride calculations matching C/Rust `repr(C)` specifications. `Slice` encapsulates guest memory spans `(ptr, length)` without buffer duplication. `StringBuffer` provides UTF-8 encoding into arena memory and decoding from guest spans.
+- **Runtime Subsystem**: `ModuleInspector` performs static binary analysis on uninstantiated modules. `HostBridge` constructs typed host import tables with standard timing and panic hooks. `ModuleLoader` compiles modules via streaming or buffered paths with optional IndexedDB bytecode caching. `WasmInstance` manages active instances with dual-tier native handle access.
+- **Thread Subsystem**: `SharedMemory` allocates thread-safe `SharedArrayBuffer` memory with 32-bit atomic wait/notify synchronization. `AtomicQueue` coordinates lock-free message passing via circular ring buffers. `WorkerPool` dispatches tasks across dedicated Web Workers sharing the same compiled module and linear memory.
+
+---
+
+## 3. Core Engineering Invariants
+
+1. **Zero-Allocation Hot Paths**:
+   - Math operations in `alm` and interval evaluations in `atempo` write directly into destination buffers passed as `out` parameters.
+   - Render targets in `awgpu` update swapchain views in place within pre-allocated descriptors, eliminating garbage collection pauses during animation and simulation loops.
+
+2. **Dense Contiguous Memory**:
+   - `aecs` stores component values and entity keys in packed, contiguous arrays (`ComponentSet`, `FloatSet`). Iterations execute directly over dense memory blocks without pointer-chasing scene graphs.
+
+3. **Four-Tier Bind Frequency Slots**:
+   - `awgpu` standardizes pipeline bindings into four update frequencies (`PerFrame = 0`, `PerPhase = 1`, `PerBatch = 2`, `PerInstance = 3`), filtering redundant GPU driver state updates between draws.
+
+4. **Deterministic Plan Caching**:
+   - Both `acircuit` and `awgpu` cache topological execution orders (`_cachedPlan` in `Circuit`, `_cachedSequence` in `PassGraph`), executing in O(1) time across subsequent frames unless graph topology is explicitly invalidated.
+
+5. **Dual-Tier Hardware Interoperability**:
+   - High-level abstractions expose raw underlying handles (`GPUDevice`, `GPUBuffer`, `GPUTexture`, `GPUCommandEncoder`). Callers can execute custom imperative passes alongside managed passes without translation overhead.
+
+6. **Bounded Diagnostic Footprint**:
+   - `adiag` uses bounded ring buffers for error logging, ensuring diagnostic instrumentation cannot cause runaway memory expansion.
+
+---
+
+## 4. End-to-End Composition Example
+
+Demonstrates coordinating entity management, 3D mathematics, temporal spring dynamics, and WebGPU command execution across Atoolkit modules:
+
+```typescript
+import { EntityPool, ComponentSet, FloatSet, query2 } from "./aecs/index.js";
+import { Vec3, Mat4 } from "./alm/index.js";
+import { Spring } from "./atempo/index.js";
+import { Device, Buffer, StreamSet, BindLayout, BindTable, RasterPipeline, Target, RenderPassNode } from "./awgpu/index.js";
+import { Bus } from "./adiag/index.js";
+
+// 1. Diagnostics & Hardware Foundation
+const bus = new Bus(500);
+const gfx = await Device.create({ canvas: "#viewport" });
+bus.info({ code: "GPU_READY", raw: "Device acquired: $format$", data: { format: gfx.format } });
+
+// 2. Entity Component Storage
+const entities = new EntityPool();
+const transforms = new FloatSet(16); // stores 4x4 matrix per entity
+const tagSet = new ComponentSet<string>();
+
+const player = entities.spawn();
+transforms.set(player, Mat4.identity(new Mat4()));
+tagSet.set(player, "ActivePlayer");
+
+// 3. Temporal Harmonic Follower
+const spring = new Spring({ stiffness: 180, damping: 14, mass: 1 });
+spring.target = 5.0; // animate target elevation
+
+// 4. Managed GPU Geometry & Uniforms
+const posBuf = Buffer.createVertex(gfx, new Float32Array([-1, -1, 0,  1, -1, 0,  0, 1, 0]));
+const uboBuf = Buffer.createUniform(gfx, 64);
+
+const streams = new StreamSet().addStream(0, posBuf, "float32x3");
+const target = Target.createScreen(gfx);
+
+const bindLayout = BindLayout.builder()
+    .addUniform(0, GPUShaderStage.VERTEX)
+    .build(gfx);
+
+const bindTable = BindTable.create(gfx, bindLayout, [
+    { binding: 0, resource: uboBuf },
+]);
+
+const pipeline = RasterPipeline.create(gfx, {
+    vertex: { code: shaderSource },
+    fragment: { code: shaderSource, targets: [{ format: gfx.format }] },
+    streamSet: streams,
+    layouts: [bindLayout],
+});
+
+const pass = new RenderPassNode(target).addDraw({
+    pipeline,
+    streamSet: streams,
+    bindTables: [bindTable],
+    vertexCount: 3,
+});
+
+// Scratch matrices (zero heap allocations in render loop)
+const model = new Mat4();
+const viewProj = new Mat4();
+const mvp = new Mat4();
+Mat4.perspective(Math.PI / 4, 16 / 9, 0.1, 100, viewProj);
+
+// 5. Simulation & Render Tick
+function tick(deltaTime: number) {
+    // Evaluate continuous harmonic spring displacement
+    spring.step(deltaTime);
+    const elevation = spring.position;
+
+    // Process matching entities
+    query2(transforms, tagSet, (entity, matrixView) => {
+        Mat4.translation(0, elevation, -5, model);
+        Mat4.mul(viewProj, model, mvp);
+        uboBuf.write(gfx, mvp);
+    });
+
+    // Record and submit commands
+    const encoder = gfx.createCommandEncoder("FrameEncoder");
+    pass.execute(encoder);
+    gfx.submit(encoder);
+}
+```

package/dist/acircuit/chip.d.ts

@@ -0,0 +1,46 @@
+import { Socket, type SocketOptions } from "./socket.js";
+import type { ProcessCtx } from "./types.js";
+/**
+ * Stateless computational unit with 1-to-1 input sockets and 1-to-N output sockets.
+ */
+export declare abstract class Chip {
+    readonly id: string;
+    readonly name: string;
+    readonly inputs: Map<string, Socket>;
+    readonly outputs: Map<string, Socket>;
+    readonly metadata: Record<string, any>;
+    constructor(id: string, name: string);
+    /**
+     * Registers an input socket.
+     */
+    addInput(socketOrName: Socket | string, options?: string | SocketOptions): this;
+    /**
+     * Registers an output socket.
+     */
+    addOutput(socketOrName: Socket | string, dataType?: string): this;
+    hasInput(name: string): boolean;
+    hasOutput(name: string): boolean;
+    getInput<T extends Socket = Socket>(name: string): T | undefined;
+    getOutput<T extends Socket = Socket>(name: string): T | undefined;
+    /**
+     * Connection validation gate invoked prior to establishing a wire.
+     * Enforces socket existence and dataType compatibility when types are declared.
+     */
+    canConnectInput(inSocketName: string, outChip: Chip, outSocketName: string): boolean;
+    /**
+     * Evaluates the chip from one execution's resolved input values.
+     * Input and output values belong to the circuit run, not to the chip.
+     */
+    abstract process(inputs: Record<string, any>, ctx?: ProcessCtx<any>): Record<string, any>;
+}
+/**
+ * Transparent proxy chip delegating execution and configuration to a source chip.
+ */
+export declare class ChipProxy extends Chip {
+    readonly sourceChip: Chip;
+    constructor(id: string, sourceChip: Chip);
+    canConnectInput(inSocketName: string, outChip: Chip, outSocketName: string): boolean;
+    process(inputs: Record<string, any>, ctx?: ProcessCtx<any>): Record<string, any>;
+    clone(newId: string): ChipProxy;
+}
+//# sourceMappingURL=chip.d.ts.map

package/dist/acircuit/chip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../acircuit/chip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,8BAAsB,IAAI;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,sBAA6B;IAC5C,QAAQ,CAAC,OAAO,sBAA6B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;gBAEhC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAKpC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAc/E;;OAEG;IACH,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAcjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAEhC,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIhE,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIjE;;;OAGG;IACH,eAAe,CACX,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,IAAI,EACb,aAAa,EAAE,MAAM,GACtB,OAAO;IAYV;;;OAGG;IACH,QAAQ,CAAC,OAAO,CACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,GAAG,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,GACtB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,IAAI;IAC/B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;gBAEd,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI;IAe/B,eAAe,CACpB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,IAAI,EACb,aAAa,EAAE,MAAM,GACtB,OAAO;IAID,OAAO,CACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,GAAG,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,GACtB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAItB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;CAGlC"}

package/dist/acircuit/chip.js

@@ -0,0 +1,104 @@
+import { Socket } from "./socket.js";
+/**
+ * Stateless computational unit with 1-to-1 input sockets and 1-to-N output sockets.
+ */
+export class Chip {
+    id;
+    name;
+    inputs = new Map();
+    outputs = new Map();
+    metadata = {};
+    constructor(id, name) {
+        this.id = id;
+        this.name = name;
+    }
+    /**
+     * Registers an input socket.
+     */
+    addInput(socketOrName, options) {
+        let socket;
+        if (typeof socketOrName === "string") {
+            socket = new Socket(socketOrName, "input", options);
+        }
+        else {
+            socket = socketOrName;
+        }
+        if (socket.direction !== "input") {
+            throw new Error(`[Chip] Input socket "${socket.name}" must have input direction.`);
+        }
+        this.inputs.set(socket.name, socket);
+        return this;
+    }
+    /**
+     * Registers an output socket.
+     */
+    addOutput(socketOrName, dataType) {
+        let socket;
+        if (typeof socketOrName === "string") {
+            socket = new Socket(socketOrName, "output", dataType ? { dataType } : {});
+        }
+        else {
+            socket = socketOrName;
+        }
+        if (socket.direction !== "output") {
+            throw new Error(`[Chip] Output socket "${socket.name}" must have output direction.`);
+        }
+        this.outputs.set(socket.name, socket);
+        return this;
+    }
+    hasInput(name) { return this.inputs.has(name); }
+    hasOutput(name) { return this.outputs.has(name); }
+    getInput(name) {
+        return this.inputs.get(name);
+    }
+    getOutput(name) {
+        return this.outputs.get(name);
+    }
+    /**
+     * Connection validation gate invoked prior to establishing a wire.
+     * Enforces socket existence and dataType compatibility when types are declared.
+     */
+    canConnectInput(inSocketName, outChip, outSocketName) {
+        const inSocket = this.getInput(inSocketName);
+        const outSocket = outChip.getOutput(outSocketName);
+        if (!inSocket || !outSocket)
+            return true;
+        if (inSocket.dataType !== undefined && outSocket.dataType !== undefined) {
+            if (inSocket.dataType === "any" || outSocket.dataType === "any")
+                return true;
+            if (inSocket.dataType !== outSocket.dataType)
+                return false;
+        }
+        return true;
+    }
+}
+/**
+ * Transparent proxy chip delegating execution and configuration to a source chip.
+ */
+export class ChipProxy extends Chip {
+    sourceChip;
+    constructor(id, sourceChip) {
+        super(id, sourceChip.name);
+        this.sourceChip = sourceChip;
+        for (const socket of sourceChip.inputs.values()) {
+            this.addInput(socket.name, {
+                dataType: socket.dataType,
+                required: socket.required,
+            });
+        }
+        for (const socket of sourceChip.outputs.values()) {
+            this.addOutput(socket.name, socket.dataType);
+        }
+        Object.assign(this.metadata, sourceChip.metadata);
+    }
+    canConnectInput(inSocketName, outChip, outSocketName) {
+        return this.sourceChip.canConnectInput(inSocketName, outChip, outSocketName);
+    }
+    process(inputs, ctx) {
+        return this.sourceChip.process(inputs, ctx);
+    }
+    clone(newId) {
+        return new ChipProxy(newId, this.sourceChip);
+    }
+}
+//# sourceMappingURL=chip.js.map

package/dist/acircuit/chip.js.map

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

package/dist/acircuit/circuit.d.ts

@@ -0,0 +1,86 @@
+import { Chip } from "./chip.js";
+import { type Wire } from "./wire.js";
+import type { RunOptions, RunResult, CircuitValidationResult, SerializedCircuit, ChipFactory } from "./types.js";
+export interface CircuitOptions {
+    label?: string;
+}
+/**
+ * Directed graph with 1-to-1 input wires and 1-to-N output fan-out.
+ * Chip values exist only in the scope of a run.
+ */
+export declare class Circuit {
+    readonly label: string;
+    readonly chips: Map<string, Chip>;
+    /** Inward wires:  "inChipId:inSocket"   -> Wire (1-to-1). */
+    private readonly _inWires;
+    /** Outward wires: "outChipId:outSocket" -> Wire[] (1-to-N). */
+    private readonly _outWires;
+    /** Inward wires grouped by destination chip ID. */
+    private readonly _chipInWires;
+    /** Outward wires grouped by source chip ID. */
+    private readonly _chipOutWires;
+    private _dirtyTopo;
+    private _cachedOrder;
+    private _cachedPlan;
+    constructor(options?: CircuitOptions);
+    private _addChipWire;
+    private _removeChipWire;
+    addChip(chip: Chip): this;
+    hasChip(id: string): boolean;
+    getChip<T extends Chip = Chip>(id: string): T | undefined;
+    removeChip(chipOrId: Chip | string): this;
+    /**
+     * Connects an output socket to an input socket, replacing any existing
+     * connection on the destination input.
+     */
+    connect(outChipOrId: Chip | string, outSocketName: string, inChipOrId: Chip | string, inSocketName: string): Wire;
+    disconnect(wireOrChipId: Wire | Chip | string, inSocketName?: string): boolean;
+    disconnectAll(chipOrId: Chip | string): this;
+    getIncomingWire(chipOrId: Chip | string, socketName: string): Wire | undefined;
+    getIncomingWires(chipOrId: Chip | string): Wire[];
+    getOutgoingWires(chipOrId: Chip | string, socketName?: string): Wire[];
+    getWires(): Wire[];
+    /** Returns all chips in dependency order and rejects cycles. */
+    topoSort<T extends Chip = Chip>(force?: boolean): T[];
+    /** Executes chips in topological order with run-local input and output values. */
+    run<TCtx = unknown>(options?: RunOptions<TCtx, Chip>): RunResult<Chip>;
+    /**
+     * Statically analyzes graph topology without throwing errors.
+     * Identifies cycles, missing required inputs, type mismatches, and isolated chips.
+     */
+    validate(): CircuitValidationResult;
+    /** Returns chips with indegree 0 (zero incoming connections). */
+    getSources(): Chip[];
+    /** Returns chips with outdegree 0 (zero outgoing connections). */
+    getSinks(): Chip[];
+    /** Returns all transitive upstream ancestor chips feeding into the target chip. */
+    getUpstreamChips(chipOrId: Chip | string): Set<Chip>;
+    /** Returns all transitive downstream descendant chips fed by the target chip. */
+    getDownstreamChips(chipOrId: Chip | string): Set<Chip>;
+    /** Returns whether a directed path exists from source chip to target chip. */
+    isReachable(fromChipOrId: Chip | string, toChipOrId: Chip | string): boolean;
+    /**
+     * Dead code elimination: prunes chips that do not reach target chips.
+     * When targetChipIds is omitted, preserves all chips reaching circuit sinks.
+     */
+    pruneUnreachable(targetChipIds?: string[]): this;
+    /**
+     * Extracts an isolated subcircuit containing only the specified target chips,
+     * their transitive upstream dependencies, and internal interconnecting wires.
+     */
+    extractSubgraph(targetChipIds: string[], options?: CircuitOptions): Circuit;
+    /**
+     * Inlines a composite subcircuit chip directly into this graph,
+     * expanding its inner chips and rerouting external wires.
+     */
+    flatten(chipOrId: Chip | string, prefix?: string): this;
+    /** Clones this circuit graph with optional custom chip factory. */
+    clone(chipCloner?: (chip: Chip) => Chip): Circuit;
+    /** Merges another circuit graph into this one, optionally applying a prefix to chip IDs. */
+    merge(other: Circuit, prefix?: string): this;
+    /** Serializes circuit topology into a portable JSON structure. */
+    toJSON(): SerializedCircuit;
+    /** Reconstructs a Circuit graph from serialized JSON using a chip factory. */
+    static fromJSON(json: SerializedCircuit, chipFactory: ChipFactory): Circuit;
+}
+//# sourceMappingURL=circuit.d.ts.map

package/dist/acircuit/circuit.d.ts.map

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