muriel 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node:*)",
+      "Bash(ls:*)",
+      "Bash(bash:*)",
+      "Bash(npm test)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,175 @@
+# Lightweight Filtergraph Flow Engine
+
+A tiny, human-readable flow engine inspired by FFmpeg filtergraphs and
+Processing modes.
+
+No nodes. No operators. No DSL gymnastics.
+
+---
+
+## Core Ideas
+
+- **Named pipes** are event channels
+- **Edges describe pipelines**
+- **Arrays mean parallel**
+- **Parallel stages auto-join**
+- **Everything else is series**
+- **Worker threads are optional**
+
+---
+
+## Transform API
+
+```js
+function myTransform(options = {}) {
+  return (send, packet) => {
+    send({ ...packet, value: packet.value * 2 });
+  };
+}
+````
+
+* Outer function = configuration
+* Inner function = execution
+* Async supported
+
+---
+
+## Filtergraph Syntax
+
+An edge is:
+
+```js
+[
+  inputPipe,
+  stage1,
+  stage2,
+  ...stageN,
+  outputPipe
+]
+```
+
+### Series
+
+```js
+['post', normalize, verify, 'updated']
+```
+
+### Parallel (auto-joined)
+
+```js
+['post', [cover, audio, post], 'updated']
+```
+
+### Parallel → Series
+
+```js
+['post', [cover, audio, post], verify, backup, 'updated']
+```
+
+Semantics:
+
+```
+(post)
+   ├─► cover
+   ├─► audio
+   └─► post
+        │
+     [auto-join]
+        │
+     verify → backup → (updated)
+```
+
+No explicit barrier required.
+
+---
+
+## Producers
+
+```js
+function socket(channel) {
+  return send => {
+    setTimeout(() => {
+      send({ payload: { type: 'new-post' }, topic: channel });
+    }, 100);
+  };
+}
+```
+
+Usage:
+
+```js
+[socket('post'), 'post']
+```
+
+---
+
+## Example: Blog Builder
+
+```js
+import { flow } from './index.js';
+
+const blog = flow(
+  [
+    [socket('post'), 'post'],
+    ['post', [cover, audio, post], verify, backup, 'updated'],
+    ['updated', pagerizer, 'done']
+  ],
+  {
+    context: { user: 'alice' },
+    workers: 8 // optional
+  }
+);
+
+blog.start();
+```
+
+---
+
+## Worker Threads
+
+* Disabled when `workers === undefined`
+* Enabled with fixed pool size
+* Best for CPU-heavy transforms
+
+```js
+flow(graph, { workers: 4 });
+```
+
+---
+
+## Disposal
+
+Always explicit.
+
+```js
+blog.dispose();
+```
+
+* Removes all listeners
+* Terminates worker threads
+* Tears down entire graph
+
+---
+
+## Design Rules (Important)
+
+1. Arrays always imply parallelism
+2. Parallel stages always auto-join
+3. Join happens before the next stage
+4. Output pipes only receive joined packets
+5. Graphs are static and readable
+
+If you can draw the graph on a whiteboard, the API is correct.
+
+---
+
+## Philosophy
+
+Think **FFmpeg filtergraphs**, not Node-RED nodes.
+Think **dataflow**, not operators.
+
+---
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,246 @@
+// index.js
+import { EventEmitter } from 'events';
+import { Worker } from 'worker_threads';
+import os from 'os';
+
+/* ─────────────────────────────────────────────
+ * Pipes
+ * ───────────────────────────────────────────── */
+
+function createPipe(name) {
+  const ee = new EventEmitter();
+  return {
+    name,
+    send(packet) {
+      ee.emit('data', packet);
+    },
+    on(fn) {
+      ee.on('data', fn);
+    },
+    dispose() {
+      ee.removeAllListeners();
+    }
+  };
+}
+
+/* ─────────────────────────────────────────────
+ * Worker pool (optional)
+ * ───────────────────────────────────────────── */
+
+function createWorkerPool(size) {
+  if (size === undefined) return null;
+
+  const workers = [];
+  let cursor = 0;
+
+  for (let i = 0; i < size; i++) {
+    workers.push(
+      new Worker(
+        `
+          const { parentPort } = require('worker_threads');
+          parentPort.on('message', async ({ fn, packet }) => {
+            try {
+              const filter = eval(fn);
+              await filter(
+                out => parentPort.postMessage({ out }),
+                packet
+              );
+            } catch (err) {
+              parentPort.postMessage({ error: err.message });
+            }
+          });
+        `,
+        { eval: true }
+      )
+    );
+  }
+
+  return {
+    exec(filter, packet, send) {
+      const worker = workers[cursor++ % workers.length];
+      worker.once('message', msg => {
+        if (msg.error) throw new Error(msg.error);
+        send(msg.out);
+      });
+      worker.postMessage({ fn: filter.toString(), packet });
+    },
+    dispose() {
+      workers.forEach(w => w.terminate());
+    }
+  };
+}
+
+/* ─────────────────────────────────────────────
+ * Internal auto-join (implicit barrier)
+ * ───────────────────────────────────────────── */
+
+function autoJoin(count, next) {
+  let buffer = [];
+
+  return packet => {
+    buffer.push(packet);
+    if (buffer.length === count) {
+      const joined = {
+        ...packet,
+        branches: buffer
+      };
+      buffer = [];
+      next(joined);
+    }
+  };
+}
+
+/* ─────────────────────────────────────────────
+ * Filter execution (returns promise for async filters)
+ * ───────────────────────────────────────────── */
+
+function runFilter(filter, packet, send, pool) {
+  if (pool) {
+    return new Promise(resolve => {
+      pool.exec(filter, packet, out => {
+        send(out);
+        resolve();
+      });
+    });
+  } else {
+    const res = filter(send, packet);
+    if (res?.then) {
+      return res.catch(console.error);
+    }
+    return null; // Sync filter
+  }
+}
+
+/* ─────────────────────────────────────────────
+ * Stage compiler
+ * ───────────────────────────────────────────── */
+
+function compileStages(stages) {
+  return stages.map(stage =>
+    Array.isArray(stage)
+      ? { type: 'parallel', filters: stage }
+      : { type: 'series', filter: stage }
+  );
+}
+
+/* ─────────────────────────────────────────────
+ * Edge runner (async-aware)
+ * ───────────────────────────────────────────── */
+
+function connectEdge(input, stages, output, ctx, pool) {
+  input.on(async packet => {
+    let current = packet;
+
+    for (let i = 0; i < stages.length; i++) {
+      const stage = stages[i];
+
+      // Series stage
+      if (stage.type === 'series') {
+        let nextPacket;
+        const result = runFilter(
+          stage.filter,
+          { ...current, ...ctx },
+          out => (nextPacket = out),
+          pool
+        );
+        // Await if async
+        if (result?.then) await result;
+        current = nextPacket;
+        continue;
+      }
+
+      // Parallel stage (auto-joined)
+      if (stage.type === 'parallel') {
+        const join = autoJoin(stage.filters.length, async joined => {
+          let downstream = joined;
+
+          // Continue remaining stages after join
+          for (let j = i + 1; j < stages.length; j++) {
+            const s = stages[j];
+            if (s.type !== 'series') {
+              throw new Error('Nested parallel not supported');
+            }
+            const result = runFilter(
+              s.filter,
+              downstream,
+              out => (downstream = out),
+              pool
+            );
+            if (result?.then) await result;
+          }
+
+          output.send(downstream);
+        });
+
+        stage.filters.forEach(f =>
+          runFilter(
+            f,
+            { ...current, ...ctx },
+            join,
+            pool
+          )
+        );
+        return;
+      }
+    }
+
+    output.send(current);
+  });
+}
+
+/* ─────────────────────────────────────────────
+ * Flow (filtergraph)
+ * ───────────────────────────────────────────── */
+
+export function flow(definition, options = {}) {
+  const pipes = new Map();
+  const pool = createWorkerPool(
+    options.workers ?? undefined
+  );
+  const ctx = options.context || {};
+  const producers = [];
+
+  const getPipe = name => {
+    if (!pipes.has(name)) pipes.set(name, createPipe(name));
+    return pipes.get(name);
+  };
+
+  // First pass: set up all edges (listeners)
+  for (const edge of definition) {
+    // Producer → pipe (defer execution)
+    if (typeof edge[0] === 'function') {
+      const producer = edge[0];
+      const pipe = getPipe(edge[1]);
+      producers.push(() => producer(packet => pipe.send({ ...packet, ...ctx })));
+      continue;
+    }
+
+    // Filtergraph edge
+    const [inputName, ...rest] = edge;
+    const outputName = rest.pop();
+    const stages = compileStages(rest);
+
+    connectEdge(
+      getPipe(inputName),
+      stages,
+      getPipe(outputName),
+      ctx,
+      pool
+    );
+  }
+
+  // Auto-start producers after all edges are connected
+  queueMicrotask(() => {
+    producers.forEach(p => p());
+  });
+
+  return {
+    start() {
+      // Manual start if needed (producers auto-start on next tick)
+    },
+    dispose() {
+      pipes.forEach(p => p.dispose());
+      pool?.dispose();
+    }
+  };
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "muriel",
+  "version": "1.0.0",
+  "description": "Lightweight Filtergraph Flow Engine",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "type": "module"
+}

package/test.js

@@ -0,0 +1,524 @@
+// test.js - Tests for the muriel filtergraph flow engine
+import { flow } from './index.js';
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`✓ ${name}`);
+    passed++;
+  } catch (err) {
+    console.log(`✗ ${name}`);
+    console.log(`  ${err.message}`);
+    failed++;
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message || 'Assertion failed');
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) {
+    throw new Error(message || `Expected ${expected}, got ${actual}`);
+  }
+}
+
+// Helper to wait for microtask queue to flush
+const tick = () => new Promise(r => queueMicrotask(r));
+
+// ─────────────────────────────────────────────
+// Test: Basic producer → pipe
+// ─────────────────────────────────────────────
+
+await test('Producer sends to named pipe', async () => {
+  let received = null;
+
+  function producer(send) {
+    send({ value: 42 });
+  }
+
+  function consumer() {
+    return (send, packet) => {
+      received = packet.value;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'input'],
+    ['input', consumer(), 'output']
+  ]);
+
+  await tick();
+  assertEqual(received, 42, 'Consumer should receive value 42');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Series pipeline
+// ─────────────────────────────────────────────
+
+await test('Series pipeline processes in order', async () => {
+  const steps = [];
+
+  function producer(send) {
+    send({ value: 1 });
+  }
+
+  function step1() {
+    return (send, packet) => {
+      steps.push('step1');
+      send({ ...packet, value: packet.value + 1 });
+    };
+  }
+
+  function step2() {
+    return (send, packet) => {
+      steps.push('step2');
+      send({ ...packet, value: packet.value * 2 });
+    };
+  }
+
+  function step3() {
+    return (send, packet) => {
+      steps.push('step3');
+      send({ ...packet, value: packet.value + 10 });
+    };
+  }
+
+  let result = null;
+  function collector() {
+    return (send, packet) => {
+      result = packet.value;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', step1(), step2(), step3(), collector(), 'out']
+  ]);
+
+  await tick();
+  assertEqual(steps.join('→'), 'step1→step2→step3', 'Steps should execute in order');
+  assertEqual(result, 14, '(1+1)*2+10 = 14');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Parallel stages with auto-join
+// ─────────────────────────────────────────────
+
+await test('Parallel stages auto-join', async () => {
+  let joinedPacket = null;
+
+  function producer(send) {
+    send({ id: 'test' });
+  }
+
+  function branchA() {
+    return (send, packet) => {
+      send({ ...packet, a: 'processed-A' });
+    };
+  }
+
+  function branchB() {
+    return (send, packet) => {
+      send({ ...packet, b: 'processed-B' });
+    };
+  }
+
+  function branchC() {
+    return (send, packet) => {
+      send({ ...packet, c: 'processed-C' });
+    };
+  }
+
+  function collector() {
+    return (send, packet) => {
+      joinedPacket = packet;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', [branchA(), branchB(), branchC()], collector(), 'out']
+  ]);
+
+  await tick();
+  assert(joinedPacket !== null, 'Joined packet should exist');
+  assert(joinedPacket.branches, 'Joined packet should have branches array');
+  assertEqual(joinedPacket.branches.length, 3, 'Should have 3 branches');
+
+  const hasA = joinedPacket.branches.some(b => b.a === 'processed-A');
+  const hasB = joinedPacket.branches.some(b => b.b === 'processed-B');
+  const hasC = joinedPacket.branches.some(b => b.c === 'processed-C');
+
+  assert(hasA && hasB && hasC, 'All branches should be present');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Parallel → Series flow
+// ─────────────────────────────────────────────
+
+await test('Parallel stages followed by series stages', async () => {
+  const executionOrder = [];
+  let finalResult = null;
+
+  function producer(send) {
+    send({ value: 10 });
+  }
+
+  function parallelA() {
+    return (send, packet) => {
+      executionOrder.push('parallelA');
+      send({ ...packet, fromA: packet.value * 2 });
+    };
+  }
+
+  function parallelB() {
+    return (send, packet) => {
+      executionOrder.push('parallelB');
+      send({ ...packet, fromB: packet.value * 3 });
+    };
+  }
+
+  function afterJoin() {
+    return (send, packet) => {
+      executionOrder.push('afterJoin');
+      send({ ...packet, afterJoin: true });
+    };
+  }
+
+  function final() {
+    return (send, packet) => {
+      executionOrder.push('final');
+      finalResult = packet;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', [parallelA(), parallelB()], afterJoin(), final(), 'out']
+  ]);
+
+  await tick();
+  assert(executionOrder.includes('parallelA'), 'parallelA should execute');
+  assert(executionOrder.includes('parallelB'), 'parallelB should execute');
+  assert(executionOrder.indexOf('afterJoin') > executionOrder.indexOf('parallelA'), 'afterJoin should come after parallel');
+  assert(executionOrder.indexOf('final') > executionOrder.indexOf('afterJoin'), 'final should come after afterJoin');
+  assert(finalResult.afterJoin === true, 'afterJoin flag should be set');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Context propagation
+// ─────────────────────────────────────────────
+
+await test('Context is propagated to all stages', async () => {
+  let receivedContext = null;
+
+  function producer(send) {
+    send({ data: 'test' });
+  }
+
+  function reader() {
+    return (send, packet) => {
+      receivedContext = { user: packet.user, env: packet.env };
+      send(packet);
+    };
+  }
+
+  const graph = flow(
+    [
+      [producer, 'in'],
+      ['in', reader(), 'out']
+    ],
+    {
+      context: { user: 'alice', env: 'production' }
+    }
+  );
+
+  await tick();
+  assertEqual(receivedContext.user, 'alice', 'User context should be alice');
+  assertEqual(receivedContext.env, 'production', 'Env context should be production');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Multiple edges in graph
+// ─────────────────────────────────────────────
+
+await test('Multiple edges can share pipes', async () => {
+  let firstResult = null;
+  let secondResult = null;
+
+  function producer(send) {
+    send({ value: 5 });
+  }
+
+  function doubler() {
+    return (send, packet) => {
+      send({ ...packet, value: packet.value * 2 });
+    };
+  }
+
+  function firstCollector() {
+    return (send, packet) => {
+      firstResult = packet.value;
+      send(packet);
+    };
+  }
+
+  function adder() {
+    return (send, packet) => {
+      send({ ...packet, value: packet.value + 100 });
+    };
+  }
+
+  function secondCollector() {
+    return (send, packet) => {
+      secondResult = packet.value;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', doubler(), firstCollector(), 'middle'],
+    ['middle', adder(), secondCollector(), 'out']
+  ]);
+
+  await tick();
+  assertEqual(firstResult, 10, 'First edge: 5 * 2 = 10');
+  assertEqual(secondResult, 110, 'Second edge: 10 + 100 = 110');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Disposal cleans up resources
+// ─────────────────────────────────────────────
+
+await test('Disposal prevents further events', async () => {
+  let count = 0;
+  let sendFn = null;
+
+  function producer(send) {
+    sendFn = send;
+    send({ value: 1 });
+  }
+
+  function counter() {
+    return (send, packet) => {
+      count++;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', counter(), 'out']
+  ]);
+
+  await tick();
+  assertEqual(count, 1, 'Should have received 1 event');
+  graph.dispose();
+
+  // Try sending after disposal - should not increment
+  try {
+    sendFn({ value: 2 });
+  } catch (e) {
+    // Expected
+  }
+  // The important thing is dispose doesn't throw
+});
+
+// ─────────────────────────────────────────────
+// Test: Async transforms
+// ─────────────────────────────────────────────
+
+await test('Async transforms are supported', async () => {
+  let result = null;
+
+  function producer(send) {
+    send({ value: 1 });
+  }
+
+  function asyncDouble() {
+    return async (send, packet) => {
+      await new Promise(r => setTimeout(r, 10));
+      send({ ...packet, value: packet.value * 2 });
+    };
+  }
+
+  function collector() {
+    return (send, packet) => {
+      result = packet.value;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', asyncDouble(), collector(), 'out']
+  ]);
+
+  // Wait for async operations
+  await new Promise(r => setTimeout(r, 50));
+
+  assertEqual(result, 2, 'Async transform should double the value');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Direct pipe connection with no stages
+// ─────────────────────────────────────────────
+
+await test('Direct pipe connection with one stage', async () => {
+  let received = null;
+
+  function producer(send) {
+    send({ value: 'passthrough' });
+  }
+
+  function collector() {
+    return (send, packet) => {
+      received = packet.value;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [producer, 'in'],
+    ['in', collector(), 'out']
+  ]);
+
+  await tick();
+  assertEqual(received, 'passthrough', 'Value should pass through');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Blog builder simulation
+// ─────────────────────────────────────────────
+
+await test('Blog builder pattern simulation', async () => {
+  const processed = { cover: false, audio: false, post: false, verified: false, backed: false };
+  let finalPacket = null;
+
+  function socket(channel) {
+    return send => {
+      send({ payload: { type: 'new-post', id: 'post-123' }, topic: channel });
+    };
+  }
+
+  function cover() {
+    return (send, packet) => {
+      processed.cover = true;
+      send({ ...packet, coverPath: '/covers/post-123.avif' });
+    };
+  }
+
+  function audio() {
+    return (send, packet) => {
+      processed.audio = true;
+      send({ ...packet, audioPath: '/audio/post-123.mp3' });
+    };
+  }
+
+  function post() {
+    return (send, packet) => {
+      processed.post = true;
+      send({ ...packet, postPath: '/posts/post-123.html' });
+    };
+  }
+
+  function verify() {
+    return (send, packet) => {
+      processed.verified = true;
+      const allBranches = packet.branches || [];
+      const hasCover = allBranches.some(b => b.coverPath);
+      const hasAudio = allBranches.some(b => b.audioPath);
+      const hasPost = allBranches.some(b => b.postPath);
+      send({ ...packet, valid: hasCover && hasAudio && hasPost });
+    };
+  }
+
+  function backup() {
+    return (send, packet) => {
+      processed.backed = true;
+      send({ ...packet, backedUp: true });
+    };
+  }
+
+  function collector() {
+    return (send, packet) => {
+      finalPacket = packet;
+      send(packet);
+    };
+  }
+
+  const blog = flow(
+    [
+      [socket('post'), 'post'],
+      ['post', [cover(), audio(), post()], verify(), backup(), collector(), 'updated']
+    ],
+    {
+      context: { user: 'alice' }
+    }
+  );
+
+  await tick();
+  assert(processed.cover, 'Cover should be processed');
+  assert(processed.audio, 'Audio should be processed');
+  assert(processed.post, 'Post should be processed');
+  assert(processed.verified, 'Should be verified');
+  assert(processed.backed, 'Should be backed up');
+  assert(finalPacket.valid, 'Final packet should be valid');
+  assertEqual(finalPacket.user, 'alice', 'Context should be available');
+  blog.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Test: Delayed producer (setTimeout)
+// ─────────────────────────────────────────────
+
+await test('Delayed producer with setTimeout', async () => {
+  let received = null;
+
+  function delayedProducer(send) {
+    setTimeout(() => send({ value: 'delayed' }), 20);
+  }
+
+  function collector() {
+    return (send, packet) => {
+      received = packet.value;
+      send(packet);
+    };
+  }
+
+  const graph = flow([
+    [delayedProducer, 'in'],
+    ['in', collector(), 'out']
+  ]);
+
+  await new Promise(r => setTimeout(r, 50));
+  assertEqual(received, 'delayed', 'Should receive delayed value');
+  graph.dispose();
+});
+
+// ─────────────────────────────────────────────
+// Summary
+// ─────────────────────────────────────────────
+
+console.log('\n─────────────────────────────────────────────');
+console.log(`Tests: ${passed + failed} | Passed: ${passed} | Failed: ${failed}`);
+console.log('─────────────────────────────────────────────');
+
+process.exit(failed > 0 ? 1 : 0);