brass-runtime 1.16.0 → 1.17.0

package/docs/wasm-fiber-engine.md

@@ -0,0 +1,117 @@
+# Brass Runtime WASM Fiber Engine
+
+Este repo mantiene la estructura original de `brass-runtime`: el package se publica desde la raíz del repositorio, no desde `packages/brass-runtime`.
+
+## Qué cambió
+
+Se agregó un engine interno experimental para mover el estado de suspensión de las fibras hacia un bridge WASM:
+
+- `src/core/runtime/engine/types.ts`: contrato `FiberEngine`.
+- `src/core/runtime/engine/JsFiberEngine.ts`: fallback JS que usa el `RuntimeFiber` actual.
+- `src/core/runtime/engine/WasmFiberEngine.ts`: engine experimental JS/WASM.
+- `src/core/runtime/engine/opcodes.ts`: representación interna del `Async` actual como plan/opcodes.
+- `src/core/runtime/engine/bridge/ReferenceWasmBridge.ts`: bridge de referencia, sin compilar Rust, útil para tests locales.
+- `src/core/runtime/engine/bridge/WasmPackFiberBridge.ts`: adapter para el output de `wasm-pack`.
+- `src/core/runtime/hostAction.ts`: efectos host declarativos HTTP/DB/Queue/custom.
+- `crates/brass-runtime-wasm-engine`: crate Rust/WASM.
+- `src/core/runtime/bench/heap-per-suspended-fiber.ts`: benchmark de heap por fibra suspendida.
+
+## Uso
+
+El modo por defecto sigue siendo JS:
+
+```ts
+const runtime = Runtime.make({});
+```
+
+Modo experimental sin compilar Rust:
+
+```ts
+const runtime = new Runtime({
+  env: {},
+  engine: "wasm-reference",
+});
+```
+
+Modo WASM real:
+
+```ts
+const runtime = new Runtime({
+  env: {},
+  engine: "wasm",
+});
+```
+
+## Host actions declarativas
+
+```ts
+import { Runtime, fromHostAction } from "brass-runtime";
+
+const runtime = new Runtime({
+  env: {},
+  engine: "wasm-reference",
+  hostExecutor: {
+    async execute(action, ctx) {
+      // Acá vive fetch/axios/db/queue real.
+      return { kind: "ok", value: { ok: true } };
+    },
+  },
+});
+
+const result = await runtime.toPromise(
+  fromHostAction({ kind: "custom", target: "my-side-effect" })
+);
+```
+
+Con `fromPromiseAbortable`, la closure host sigue viviendo en JS porque Axios/fetch/DB viven en Node. El engine WASM reduce la parte de continuación/scheduler/fiber state de Brass. Para reducir más heap por suspensión, usá `fromHostAction`, que representa el efecto como acción declarativa y deja el side effect real en el `HostExecutor`.
+
+## Publicación desde este repo
+
+```bash
+npm install
+npm run build
+npm pack --dry-run
+npm publish
+```
+
+Si querés publicar con el `.wasm` real incluido:
+
+```bash
+cargo --version
+wasm-pack --version
+npm run build:wasm
+npm run build
+npm pack --dry-run
+npm publish
+```
+
+## Benchmark
+
+```bash
+npm run benchmark heap-suspended-fiber
+```
+
+The direct benchmark script is still available when you want a specific engine
+or longer suspension window:
+
+```bash
+node --expose-gc ./node_modules/.bin/tsx src/core/runtime/bench/heap-per-suspended-fiber.ts \
+  --engine wasm \
+  --mode host-action \
+  --fibers 10000 \
+  --delayMs 2000
+node --expose-gc ./node_modules/.bin/tsx src/core/runtime/bench/heap-per-suspended-fiber.ts --engine ts --mode closure
+```
+
+## WASM fiber registry + wakeups
+
+The WASM engine now also owns a compact `BrassWasmFiberRegistry` used by the TS engine facade to track fiber lifecycle metadata and coalesce wakeups.
+
+The public TypeScript `Runtime` API is unchanged. When `engine: "wasm"` is selected:
+
+- TS still executes host callbacks, promises, finalizers and Node integrations.
+- Rust/WASM tracks fiber states: queued, running, suspended, done, failed and interrupted.
+- Rust/WASM owns a wakeup queue so repeated wakeups for the same fiber are coalesced before TS schedules more work.
+- `runtime.stats().fiberRegistry` exposes registry counters for observability.
+
+This keeps the high-level Brass API ergonomic while moving another hot coordination path into a compact Rust state machine.

package/docs/wasm-scheduler-state-machine.md

@@ -0,0 +1,122 @@
+# WASM scheduler state machine
+
+The scheduler bookkeeping hot path lives in `brass-runtime-wasm-engine` when the scheduler is created with `engine: "wasm"` or `engine: "auto"` and the WASM package is available. The public TypeScript scheduler API remains unchanged.
+
+## What moved to Rust/WASM
+
+- scheduler phase: `idle`, `scheduledMicro`, `scheduledMacro`, `flushing`
+- inferred caller lanes from task tags
+- one bounded task-ref queue per lane
+- round-robin lane rotation
+- per-lane execution budget
+- global flush budget accounting
+- micro vs macro scheduling policy
+- global counters for enqueued/executed/dropped tasks
+- per-lane counters for enqueued/executed/dropped tasks
+- counters for budget yields and flush cycles
+
+## What stays in TypeScript
+
+- the actual task callbacks
+- `queueMicrotask`, `setImmediate`, `MessageChannel`, `setTimeout`
+- error logging
+- Node/browser integration
+
+This is intentional: WASM coordinates scheduler state and returns task refs, but JS still owns and executes side effects.
+
+## Lane inference
+
+Rust and TypeScript now use the same tag convention:
+
+```txt
+lane:<caller>|<task-label>
+caller:<caller>|<task-label>
+<fallback-prefix>#<id>.<task-label>
+```
+
+`Runtime.withLane("bff-security/generate")` ultimately schedules fibers with a `lane:` tag, so Brass does not need to know anything about the BFF implementation. It only sees a stable caller key.
+
+When no explicit lane is set, the TypeScript runtime infers a lane once from the first non-Brass callsite and then passes that stable lane to JS or WASM scheduler state. Child fibers inherit their parent lane.
+
+## Bounded queues and budgets
+
+```ts
+const scheduler = new Scheduler({
+  engine: "wasm",
+  laneCapacity: 512,
+  laneBudget: 32,
+  flushBudget: 1024,
+  maxLanes: 256,
+});
+```
+
+Semantics:
+
+- `laneCapacity`: max queued task refs per lane. When a lane is full, the newly enqueued task is dropped, `droppedTasks` increments, and TS maps the Rust policy to `Scheduler.schedule() === "dropped"`. Runtime fibers fail fast rather than hanging.
+- `laneBudget`: max tasks a single lane may run before the scheduler rotates to the next non-empty lane.
+- `flushBudget`: max tasks per flush before yielding back to the event loop.
+- `maxLanes`: max distinct inferred lanes before new unknown callers are grouped into `overflow`.
+
+## Usage
+
+```ts
+const scheduler = new Scheduler({ engine: "wasm" });
+const runtime = Runtime.make({}, scheduler).withLane("bff-security/validate");
+
+await runtime.toPromise(effect);
+```
+
+For production-safe behavior use auto mode:
+
+```ts
+const scheduler = new Scheduler({ engine: "auto" });
+```
+
+`auto` uses WASM when `wasm/pkg/brass_runtime_wasm_engine.js` is available and falls back to the JS implementation otherwise.
+
+## Introspection
+
+```ts
+console.log(scheduler.stats());
+```
+
+The WASM path returns counters from the Rust state machine:
+
+```ts
+{
+  engine: "wasm",
+  fallbackUsed: false,
+  data: {
+    phase: "idle",
+    len: 0,
+    capacity: 512,
+    scheduledFlushes: 10,
+    completedFlushes: 10,
+    enqueuedTasks: 1000,
+    executedTasks: 1000,
+    droppedTasks: 0,
+    yieldedByBudget: 0,
+    lanes: [
+      {
+        key: "bff-security/validate",
+        len: 0,
+        capacity: 512,
+        enqueuedTasks: 1000,
+        executedTasks: 1000,
+        droppedTasks: 0
+      }
+    ]
+  }
+}
+```
+
+## Build
+
+After changing Rust, rebuild the WASM package locally:
+
+```bash
+npm run build:wasm
+npm run build
+```
+
+The TypeScript changes compile without requiring the WASM artifact, but `engine: "wasm"` requires the generated `wasm/pkg` output at runtime.

package/docs/wasm-stream-chunks.md

@@ -0,0 +1,54 @@
+# WASM stream chunks
+
+This adds an optional WASM-backed chunk buffer for `ZStream`.
+
+The goal is not to move all stream semantics to Rust. The goal is to make the hot path chunk-aware so downstream operators can process arrays/batches instead of one element at a time.
+
+## API
+
+```ts
+import { chunks, chunksP, mapChunksEffectP } from "brass-runtime";
+```
+
+### Direct stream API
+
+```ts
+const chunked = chunks(stream, 1024, { engine: "wasm" });
+```
+
+`chunked` has type:
+
+```ts
+ZStream<R, E, readonly A[]>
+```
+
+### Pipeline API
+
+```ts
+const batched = via(stream, chunksP<number>(1024, { engine: "wasm" }));
+```
+
+### Effectful chunk mapping
+
+```ts
+const processed = via(
+  stream,
+  mapChunksEffectP(1024, (chunk) =>
+    asyncSucceed(chunk.map((n) => n * 2))
+  , { engine: "wasm" })
+);
+```
+
+## Engine modes
+
+```ts
+{ engine: "js" }    // always JS arrays
+{ engine: "wasm" }  // require wasm/pkg
+{ engine: "auto" }  // WASM when available, otherwise JS fallback
+```
+
+## Why this shape
+
+Crossing Node/JS ↔ WASM for every element can be slower than plain JS. This implementation makes WASM useful as a chunk boundary and gives the rest of the stream pipeline a batch-oriented representation.
+
+The next optimization step would be to add specialized Rust operations for primitive chunks, for example numeric `sum`, `min`, `max`, `filterGt`, or binary/typed-array transforms. Generic JS callbacks should stay in TS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brass-runtime",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Effect runtime utilities for TypeScript",
   "license": "MIT",
   "author": "Augusto Vivaldelli",
@@ -38,6 +38,11 @@
       "import": "./dist/observability/index.mjs",
       "require": "./dist/observability/index.cjs"
     },
+    "./perf": {
+      "types": "./dist/perf/index.d.ts",
+      "import": "./dist/perf/index.mjs",
+      "require": "./dist/perf/index.cjs"
+    },
     "./agent": {
       "types": "./dist/agent/index.d.ts",
       "import": "./dist/agent/index.mjs",
@@ -51,6 +56,8 @@
     "dist",
     "wasm/pkg",
     "README.md",
+    "CHANGELOG.md",
+    "docs",
     "LICENSE",
     "package.json"
   ],
@@ -106,13 +113,25 @@
     "agent:vscode:reinstall:global": "npm run agent:vscode:uninstall:global && npm run agent:vscode:install:global",
     "benchmark": "tsx src/benchmarks/runner.ts",
     "benchmark:json": "tsx src/benchmarks/runner.ts --json",
+    "benchmark:runtime": "tsx src/benchmarks/runner.ts runtime-performance-track",
+    "benchmark:runtime:budget": "node scripts/check-runtime-benchmark-budget.mjs",
     "benchmark:http": "tsx src/benchmarks/runner.ts http-concurrent",
     "benchmark:http:soak": "BRASS_HTTP_BENCH_MODE=soak tsx src/benchmarks/runner.ts http-concurrent",
     "benchmark:http:budget": "node scripts/check-http-benchmark-budget.mjs",
+    "benchmark:http:ramp": "tsx src/benchmarks/runner.ts http-ramp-tps",
     "benchmark:adaptive": "tsx src/benchmarks/runner.ts adaptive-limiter-soak",
     "benchmark:adaptive:soak": "BRASS_ADAPTIVE_BENCH_MODE=soak tsx src/benchmarks/runner.ts adaptive-limiter-soak",
     "benchmark:observability": "tsx src/benchmarks/runner.ts observability-overhead",
     "benchmark:observability:budget": "node scripts/check-observability-benchmark-budget.mjs",
+    "benchmark:perf": "tsx src/perf/cli.ts --json",
+    "perf": "tsx src/perf/cli.ts",
+    "perf:json": "tsx src/perf/cli.ts --json",
+    "perf:runtime:ab": "tsx src/perf/cli.ts --profile runtime-ab",
+    "perf:runtime:soak": "tsx src/perf/cli.ts --profile runtime-soak",
+    "perf:runtime:budget": "tsx src/perf/budgetCli.ts",
+    "perf:http:memory": "tsx src/perf/cli.ts --profile http-memory",
+    "perf:history": "tsx src/perf/cli.ts --record-history",
+    "release:check": "npm run test:types && npm test && npm run build:ts && npm run validate:cjs && npm run perf:runtime:budget && npm run benchmark:runtime:budget && npm run benchmark:http:budget && npm run benchmark:observability:budget",
     "example:observability:express": "tsx src/examples/observabilityExpress.ts",
     "example:observability:fastify": "tsx src/examples/observabilityFastify.ts",
     "example:observability:nest": "tsx src/examples/observabilityNest.ts",
@@ -143,6 +162,7 @@
   },
   "homepage": "https://github.com/BaldrVivaldelli/brass-runtime#readme",
   "bin": {
-    "brass-agent": "dist/agent/cli/main.cjs"
+    "brass-agent": "dist/agent/cli/main.cjs",
+    "brass-perf": "dist/perf/cli.cjs"
   }
 }

package/dist/chunk-45F7OKGT.cjs

@@ -1,104 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
-
-var _chunkWQ5QNU5Rcjs = require('./chunk-WQ5QNU5R.cjs');
-
-
-
-
-
-
-var _chunkDJQ7OMMBcjs = require('./chunk-DJQ7OMMB.cjs');
-
-// src/core/runtime/combinators.ts
-function sleep(ms) {
-  return _chunkDJQ7OMMBcjs.asyncEffect.call(void 0, (_env, cb) => {
-    const delay = Math.max(0, Math.floor(ms));
-    const id = setTimeout(() => cb({ _tag: "Success", value: void 0 }), delay);
-    return () => clearTimeout(id);
-  });
-}
-function timeout(effect, ms) {
-  return _chunkDJQ7OMMBcjs.asyncEffect.call(void 0, (env, cb) => {
-    let done = false;
-    let timerId;
-    let effectRunning = true;
-    timerId = setTimeout(() => {
-      if (done) return;
-      done = true;
-      effectRunning = false;
-      cb({
-        _tag: "Failure",
-        cause: { _tag: "Fail", error: { _tag: "TimeoutError", ms } }
-      });
-    }, Math.max(0, Math.floor(ms)));
-    const runtime = _chunkWQ5QNU5Rcjs.unsafeGetCurrentRuntime.call(void 0, );
-    const fiber = runtime.fork(effect);
-    fiber.join((exit) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timerId);
-      cb(exit);
-    });
-    return () => {
-      if (done) return;
-      done = true;
-      clearTimeout(timerId);
-      fiber.interrupt();
-    };
-  });
-}
-function retry(effect, policy) {
-  const shouldRetry = _nullishCoalesce(policy.shouldRetry, () => ( (() => true)));
-  const jitter = _nullishCoalesce(policy.jitter, () => ( "full"));
-  const maxElapsedMs = policy.maxElapsedMs;
-  const computeDelay = (attempt) => {
-    const exp = policy.baseDelayMs * Math.pow(2, attempt);
-    const capped = Math.min(exp, policy.maxDelayMs);
-    if (jitter === "none") return capped;
-    return Math.floor(Math.random() * capped);
-  };
-  const loop = (attempt, startedAt) => _chunkDJQ7OMMBcjs.asyncFold.call(void 0, 
-    effect,
-    (error) => {
-      if (attempt >= policy.maxRetries) return _chunkDJQ7OMMBcjs.asyncFail.call(void 0, error);
-      if (!shouldRetry(error, attempt)) return _chunkDJQ7OMMBcjs.asyncFail.call(void 0, error);
-      if (maxElapsedMs !== void 0) {
-        const elapsed = performance.now() - startedAt;
-        if (elapsed >= maxElapsedMs) return _chunkDJQ7OMMBcjs.asyncFail.call(void 0, error);
-      }
-      const delay = computeDelay(attempt);
-      return _chunkDJQ7OMMBcjs.asyncFlatMap.call(void 0, sleep(delay), () => loop(attempt + 1, startedAt));
-    },
-    (value) => _chunkDJQ7OMMBcjs.asyncSucceed.call(void 0, value)
-  );
-  return _chunkDJQ7OMMBcjs.asyncFlatMap.call(void 0, 
-    { _tag: "Sync", thunk: () => performance.now() },
-    (startedAt) => loop(0, startedAt)
-  );
-}
-function retryN(effect, n) {
-  return retry(effect, {
-    maxRetries: n,
-    baseDelayMs: 0,
-    maxDelayMs: 0,
-    jitter: "none"
-  });
-}
-function retryWithBackoff(effect, opts = {}) {
-  return retry(effect, {
-    maxRetries: _nullishCoalesce(opts.maxRetries, () => ( 3)),
-    baseDelayMs: _nullishCoalesce(opts.baseDelayMs, () => ( 100)),
-    maxDelayMs: _nullishCoalesce(opts.maxDelayMs, () => ( 1e4)),
-    maxElapsedMs: opts.maxElapsedMs,
-    shouldRetry: opts.shouldRetry,
-    jitter: "full"
-  });
-}
-
-
-
-
-
-
-
-exports.sleep = sleep; exports.timeout = timeout; exports.retry = retry; exports.retryN = retryN; exports.retryWithBackoff = retryWithBackoff;

package/dist/chunk-7V4KY4RL.mjs

@@ -1,104 +0,0 @@
-import {
-  unsafeGetCurrentRuntime
-} from "./chunk-G6IQOE4P.mjs";
-import {
-  asyncEffect,
-  asyncFail,
-  asyncFlatMap,
-  asyncFold,
-  asyncSucceed
-} from "./chunk-NOYZIMUJ.mjs";
-
-// src/core/runtime/combinators.ts
-function sleep(ms) {
-  return asyncEffect((_env, cb) => {
-    const delay = Math.max(0, Math.floor(ms));
-    const id = setTimeout(() => cb({ _tag: "Success", value: void 0 }), delay);
-    return () => clearTimeout(id);
-  });
-}
-function timeout(effect, ms) {
-  return asyncEffect((env, cb) => {
-    let done = false;
-    let timerId;
-    let effectRunning = true;
-    timerId = setTimeout(() => {
-      if (done) return;
-      done = true;
-      effectRunning = false;
-      cb({
-        _tag: "Failure",
-        cause: { _tag: "Fail", error: { _tag: "TimeoutError", ms } }
-      });
-    }, Math.max(0, Math.floor(ms)));
-    const runtime = unsafeGetCurrentRuntime();
-    const fiber = runtime.fork(effect);
-    fiber.join((exit) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timerId);
-      cb(exit);
-    });
-    return () => {
-      if (done) return;
-      done = true;
-      clearTimeout(timerId);
-      fiber.interrupt();
-    };
-  });
-}
-function retry(effect, policy) {
-  const shouldRetry = policy.shouldRetry ?? (() => true);
-  const jitter = policy.jitter ?? "full";
-  const maxElapsedMs = policy.maxElapsedMs;
-  const computeDelay = (attempt) => {
-    const exp = policy.baseDelayMs * Math.pow(2, attempt);
-    const capped = Math.min(exp, policy.maxDelayMs);
-    if (jitter === "none") return capped;
-    return Math.floor(Math.random() * capped);
-  };
-  const loop = (attempt, startedAt) => asyncFold(
-    effect,
-    (error) => {
-      if (attempt >= policy.maxRetries) return asyncFail(error);
-      if (!shouldRetry(error, attempt)) return asyncFail(error);
-      if (maxElapsedMs !== void 0) {
-        const elapsed = performance.now() - startedAt;
-        if (elapsed >= maxElapsedMs) return asyncFail(error);
-      }
-      const delay = computeDelay(attempt);
-      return asyncFlatMap(sleep(delay), () => loop(attempt + 1, startedAt));
-    },
-    (value) => asyncSucceed(value)
-  );
-  return asyncFlatMap(
-    { _tag: "Sync", thunk: () => performance.now() },
-    (startedAt) => loop(0, startedAt)
-  );
-}
-function retryN(effect, n) {
-  return retry(effect, {
-    maxRetries: n,
-    baseDelayMs: 0,
-    maxDelayMs: 0,
-    jitter: "none"
-  });
-}
-function retryWithBackoff(effect, opts = {}) {
-  return retry(effect, {
-    maxRetries: opts.maxRetries ?? 3,
-    baseDelayMs: opts.baseDelayMs ?? 100,
-    maxDelayMs: opts.maxDelayMs ?? 1e4,
-    maxElapsedMs: opts.maxElapsedMs,
-    shouldRetry: opts.shouldRetry,
-    jitter: "full"
-  });
-}
-
-export {
-  sleep,
-  timeout,
-  retry,
-  retryN,
-  retryWithBackoff
-};