brass-runtime 1.15.0 → 1.16.1

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.15.0",
+  "version": "1.16.1",
   "description": "Effect runtime utilities for TypeScript",
   "license": "MIT",
   "author": "Augusto Vivaldelli",
@@ -18,11 +18,31 @@
       "import": "./dist/http/index.mjs",
       "require": "./dist/http/index.cjs"
     },
+    "./http/testing": {
+      "types": "./dist/http/testing.d.ts",
+      "import": "./dist/http/testing.mjs",
+      "require": "./dist/http/testing.cjs"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.mjs",
+      "require": "./dist/schema/index.cjs"
+    },
     "./core": {
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.mjs",
       "require": "./dist/core/index.cjs"
     },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "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",
@@ -36,6 +56,8 @@
     "dist",
     "wasm/pkg",
     "README.md",
+    "CHANGELOG.md",
+    "docs",
     "LICENSE",
     "package.json"
   ],
@@ -91,6 +113,29 @@
     "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",
+    "smoke:observability:collector": "node scripts/observability-collector-smoke.mjs",
     "context": "node scripts/context-pack.mjs",
     "test:coverage:html": "COVERAGE_GATE=off vitest run --coverage --reporter=default",
     "build:wasm": "cd crates/brass-runtime-wasm-engine && wasm-pack build --target nodejs --out-dir ../../wasm/pkg",
@@ -117,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"
   }
 }