@panagos/jojoscript 0.8.0 → 0.9.0

package/README.md

@@ -1,4 +1,4 @@
-# JojoScript 0.8.0
+# JojoScript 0.9.0
 
 JojoScript is a small JavaScript-compatible language and runtime for
 expressive, composable pipelines. It adds lightweight syntax for declarations,
@@ -6,7 +6,8 @@ functions, pattern matching, type annotations, and pipelines while preserving
 ordinary JavaScript. Its compiler uses a lightweight lexer and source
 transformations rather than a full AST, keeping the toolchain compact. The
 project also provides lazy and async collection operators, checkpointing,
-retries, metrics, pipeline graphing, CLI workflows, and VS Code editor support.
+retries, metrics, pipeline graphing, CLI workflows, effect handlers, and
+VS Code editor support.
 
 See [CHANGELOG.md](CHANGELOG.md) for release history and
 [example/](example/) for a complete runnable application that exercises
@@ -305,7 +306,368 @@ auto-imported):
 See [ITERATOR_PROPOSAL.md](ITERATOR_PROPOSAL.md) and [ITERATORS.md](ITERATORS.md)
 for the full laziness/memory model.
 
-## JavaScript compatibility
+## Effect Handlers
+
+> This is a deliberately simplified effect-handler model, not full
+> algebraic effects with delimited continuations (no `resume`, no
+> resuming a suspended computation zero/more-than-once, no re-throwing to
+> an outer handler after partial handling). What it *does* give you: named
+> effects, dynamic handler dispatch, nesting/overriding, deterministic
+> mock handlers, record/replay, and a `parallel()` effect — all with plain
+> JavaScript interop. If you already know algebraic effects from OCaml/Eff/
+> Koka, think "a practical subset", not "the whole theory".
+
+The central idea:
+
+```
+Pipeline
+  describes computation
+
+Execution Plan
+  describes how the computation can be executed
+
+Effect
+  describes an external capability/action
+
+Effect Handler
+  decides how that capability/action is interpreted
+```
+
+**Describe the computation once, choose its interpretation separately.**
+
+### What an effect is
+
+`effect name(params)` declares a named capability — "this program wants to
+fetch a user", not "this program makes an HTTP GET request". It compiles to
+a plain runtime call:
+
+```jojo
+effect fetchUser(id)
+effect saveUser(user)
+```
+
+becomes:
+
+```js
+const fetchUser = defineEffect("fetchUser", ["id"])
+const saveUser = defineEffect("saveUser", ["user"])
+```
+
+Calling `fetchUser(id)` doesn't run anything itself — it looks up the
+currently active handler for `"fetchUser"` and delegates to it. **Calling an
+effect always returns a Promise**, even if the active handler is
+synchronous, so the calling code never has to know or care whether the
+handler in charge is a real (often async) implementation or a fake (often
+sync) one.
+
+### What an effect handler is, and how to install one
+
+A handler supplies the implementation for one or more named effects, for
+the dynamic extent of a block:
+
+```jojo
+effect fetchUser(id)
+effect saveUser(user)
+
+users
+  |> map(user => fetchUser(user.id))
+  |> map(saveUser)
+```
+
+runs under:
+
+```jojo
+handle {
+  fetchUser: id => http.get(`/users/${id}`),
+  saveUser: user => database.save(user)
+} {
+  users
+    |> map(user => fetchUser(user.id))
+    |> map(saveUser)
+}
+```
+
+which compiles to:
+
+```js
+(await withHandlers({
+  fetchUser: id => http.get(`/users/${id}`),
+  saveUser: user => database.save(user)
+}, async () => {
+  users
+    |> map(user => fetchUser(user.id))
+    |> map(saveUser)
+}))
+```
+
+A handler value can be a plain function, or a `{ handle, deterministic }`
+descriptor when you want to declare it explicitly deterministic (useful for
+inspection — see below):
+
+```jojo
+handle {
+  fetchUser: { handle: id => fakeUser(id), deterministic: true }
+} {
+  ...
+}
+```
+
+Because `handle { ... } { ... }` compiles to `await withHandlers(...)`, it
+must be used inside an `async fn`/`async function`, or at the top level of
+an ES module (Node's top-level `await`) — the same requirement the existing
+`|> await` pipeline stage already has.
+
+### How the same program runs under different handlers
+
+The program never mentions which handler is active — only the caller
+decides that, by choosing which `handle { ... }` wraps it:
+
+```jojo
+effect fetchUser(id)
+effect saveUser(user)
+
+async fn syncUser(id) {
+  user := await fetchUser(id)
+  return await saveUser(user)
+}
+
+async fn syncUserInProduction(id) {
+  return handle {
+    fetchUser: id => http.get(`/users/${id}`),
+    saveUser: user => database.save(user)
+  } {
+    return await syncUser(id)
+  }
+}
+
+async fn syncUserInTests(id) {
+  return handle {
+    fetchUser: id => ({ id, name: "Fake User" }),
+    saveUser: user => ({ ...user, savedTo: "in-memory" })
+  } {
+    return await syncUser(id)
+  }
+}
+```
+
+`syncUser` is identical in both cases; only the handler map differs. See
+[example/src/effects/multiple-handlers.jojo](example/src/effects/multiple-handlers.jojo)
+and
+[example/src/effects/deterministic-testing.jojo](example/src/effects/deterministic-testing.jojo).
+
+### Nested handlers and resolution rules
+
+`handle` blocks nest. An inner handler for a given effect name **overrides**
+an outer one; an inner handler map that doesn't mention an effect leaves it
+falling through to the next outer handler that does:
+
+```jojo
+handle {
+  fetchUser: outerFake
+} {
+  handle {
+    fetchUser: innerFake
+  } {
+    users |> map(fetchUser) // resolves to innerFake
+  }
+
+  users |> map(fetchUser) // resolves to outerFake, outside the inner block
+}
+```
+
+Resolution walks from the innermost active `handle` block outward, taking
+the first one that declares the effect. Once a `handle` block's body
+finishes, its handlers are gone — code that runs afterwards (or a lazy
+pipeline consumed afterwards, see the caveat below) no longer sees them.
+
+### Error handling
+
+| Situation | Result |
+|---|---|
+| Effect invoked with no active handler for it | `UnhandledEffectError`: `` Unhandled effect: fetchUser\nNo handler registered for effect "fetchUser" `` |
+| Handler throws (or its returned Promise rejects) | `EffectHandlerError`, naming the effect and wrapping the original error as `.cause` |
+| Handler value isn't a function or `{ handle, deterministic }` | `TypeError`, thrown immediately when `handle { ... }` installs it, not at call time |
+| A handler recursively invokes the same effect (directly, or indirectly through another effect) | `RecursiveEffectError`, naming the effect |
+| Effect invoked entirely outside any `handle` block | Same as "no active handler" — `UnhandledEffectError` |
+
+### `parallel()` as an effect
+
+`items |> parallel(n) |> map(fn)` is effect-backed. With no handler
+installed, it behaves exactly as before (a bounded-concurrency worker
+pool — existing programs are unaffected). Installing a `PARALLEL` handler
+lets a different interpretation take over completely:
+
+```jojo
+handle {
+  PARALLEL: async ({ items, fn, concurrency }) => {
+    // deterministic, strictly sequential — great for tests
+    results := []
+    for await (const item of items) results.push(await fn(item))
+    return results
+  }
+} {
+  numbers |> parallel(8) |> map(process) |> toArrayAsync |> await
+}
+```
+
+A `PARALLEL` handler receives `{ items, fn, concurrency, meta }` and returns
+an (async) iterable of results in order — the same contract the built-in
+implementation follows. This lets production code use real concurrency,
+tests force deterministic sequential execution, and a debugging handler
+record scheduling information, all without changing the pipeline. See
+[example/src/effects/parallel-effect.jojo](example/src/effects/parallel-effect.jojo).
+
+### Effects in the execution plan
+
+`jojo graph`/`analyzePipelines` expose which pipeline nodes reference which
+declared effects, and a best-effort static "is a handler for it declared
+anywhere in this file?" signal:
+
+```jojo
+effect fetchUser(id)
+effect saveUser(user)
+
+handle {
+  fetchUser: id => ({ id })
+} {
+  users
+    |> map(user => fetchUser(user.id))
+    |> parallel(8)
+    |> map(saveUser)
+}
+```
+
+```
+SOURCE users
+      │
+      ▼
+MAP user => fetchUser(user.id)  [effects: fetchUser]
+      │
+      ▼
+PARALLEL 8
+      │
+      ▼
+MAP saveUser  [effects: saveUser]
+      │
+      ▼
+RESULT
+```
+
+Programmatically, `analyzePipelines(source)` returns each pipeline's graph
+with an `effects` array:
+
+```js
+[
+  { name: "fetchUser", nodeId: "node-1", staticallyHandled: true },
+  { name: "saveUser", nodeId: "node-3", staticallyHandled: false }
+]
+```
+
+`staticallyHandled` is a textual, best-effort signal (a `handle { name: ... }`
+naming that effect was found somewhere in the file) — it cannot see handlers
+installed conditionally or dynamically at runtime. For that, call
+`describeHandlers()` from inside a running `handle { ... }` block: it
+reports, per currently-handled effect, whether the installed handler
+declared itself `deterministic`, and the declaring effect's `sideEffecting`/
+`replayable` metadata (from `effect name(params)`'s options, or defaults —
+`sideEffecting: true`, `replayable: false`).
+
+### Effects and checkpoint/resume
+
+Consider:
+
+```jojo
+effect fetchUser(id)
+
+ids
+  |> mapAsync(fetchUser)
+  |> checkpoint("users-fetched")
+  |> toArrayAsync
+```
+
+`checkpoint(name)` either streams items through once and durably saves them
+all, or — if a checkpoint for `name` already completed — returns the saved
+items **without ever touching the upstream iterable at all**. This gives
+effects placed before a checkpoint a specific, non-magical guarantee:
+
+- **Once a checkpoint has completed**, a later run does **not** re-invoke
+  the upstream effect(s) — the saved items are restored instead. This is
+  restoration from checkpoint state, not effect replay: the checkpoint
+  store never sees the individual `fetchUser` calls, only the pipeline
+  items that came out the other side.
+- **If a checkpoint never completed** (crash, first run, ...), the upstream
+  effect(s) run again from scratch on the next attempt — there is no
+  per-item resume within an incomplete checkpoint.
+
+**This is explicitly not exactly-once effect execution.** It is
+"at-least-once until the checkpoint fully completes, then exactly zero
+additional times after." A non-idempotent, non-replayable effect
+(`replayable: false`, the default) must tolerate being invoked again on a
+crash-and-retry before its checkpoint completes. Mark an effect
+`{ replayable: true }` only if calling it again with the same arguments is
+actually safe. See
+[example/src/effects/checkpoint-resume.jojo](example/src/effects/checkpoint-resume.jojo)
+and `test/effects-checkpoint.test.js` for both cases exercised end to end.
+
+### Record/replay
+
+A handler map can be wrapped to record every call (arguments + result) to
+an `EffectLog`, and later replayed from that log without running any real
+code:
+
+```js
+import { recordHandlers, replayHandlers, withHandlers } from "@panagos/jojoscript/runtime"
+import { FileEffectLog } from "@panagos/jojoscript/runtime"
+
+const log = new FileEffectLog("./fetchUser.log.json")
+
+// Recording run: calls the real handler, and appends each call to the log.
+await withHandlers(recordHandlers({ fetchUser: realFetchUser }, log), program)
+
+// Replay run: never calls realFetchUser again, just replays recorded results.
+await withHandlers(replayHandlers(["fetchUser"], log), program)
+```
+
+`EffectLog` (`MemoryEffectLog`/`FileEffectLog`) is a small, storage-agnostic
+interface (`record`/`replayNext`), mirroring `CheckpointStore` — an
+extension point for a future backend, not a full production-grade
+persistence system.
+
+### JavaScript interoperability
+
+A handler is just a normal JavaScript function — sync or async — and can
+call anything JavaScript can call:
+
+```jojo
+effect fetchUser(id)
+
+handle {
+  fetchUser: id => fetch(`/users/${id}`)
+} {
+  ...
+}
+```
+
+### Guarantees and limitations
+
+- Handler dispatch is dynamic-scope-based (an `AsyncLocalStorage` stack),
+  the same mechanism `checkpoint`/`inspect`/metrics already use for
+  execution context. Because pipeline stages are lazy, a `handle { ... }`
+  block's handlers are only active while its body is *consumed* (e.g. via
+  `toArray`/`toArrayAsync`/`reduce`/...), not merely constructed — always
+  consume (or `await`) an effectful pipeline inside the `handle` block
+  itself.
+- No delimited continuations: a handler cannot `resume` the computation
+  that invoked the effect, inspect intermediate state, or resume it more
+  than once.
+- Recursion guard: a handler invoking the same effect it is currently
+  handling (directly or through another effect) is rejected with
+  `RecursiveEffectError` rather than hanging or overflowing the stack.
+- Existing programs that never use `effect`/`handle` syntax, and existing
+  `parallel()` usage with no `PARALLEL` handler installed, are completely
+  unaffected — this is additive, opt-in syntax.
+
+
 
 JojoScript intentionally leaves ordinary JavaScript alone. You can use:
 
@@ -366,6 +728,12 @@ report, alongside one small focused module (and test) per feature. Every
 module is imported and invoked from `example/src/main.jojo`, so both
 `npm start` and `npm test` exercise the whole example.
 
+[example/src/effects/](example/src/effects/) has six focused Effect Handlers
+examples (each with a matching test under `example/test/`): basic effects,
+running the same program with multiple handlers, deterministic testing,
+`parallel()` as an effect, effect visibility in the execution plan, and the
+checkpoint/resume interaction.
+
 ```bash
 cd example
 npm install
@@ -426,4 +794,16 @@ resulting `.vsix` locally.
 - **Multi-binding declarations (`a, b := 1, 2`) are single-line only** and
   always wrap the right-hand side in `[...]`; use `[a, b] := expr()` to
   destructure a single expression instead.
+- **Effect Handlers are a simplified model, not full algebraic effects.**
+  No delimited continuations/`resume`; a handler cannot inspect or resume
+  the suspended computation, or resume it more than once. See the
+  "Effect Handlers" section for the full list of guarantees/limitations.
+- **`handle { ... } { ... }` handlers are only active while their body is
+  actually consumed.** Constructing a lazy pipeline inside a `handle` block
+  without consuming it there (no `toArray`/`toArrayAsync`/`reduce`/...) means
+  effects pulled later, outside the block, won't see its handlers.
+- **Only `PARALLEL` is a built-in effect today.** The other capabilities
+  mentioned as a long-term direction (`IO`, `HTTP`, `FILE`, `DATABASE`,
+  `SLEEP`, `TIME`, `RANDOM`, `CHECKPOINT`) are not implemented — user-defined
+  `effect` declarations cover the same need today.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panagos/jojoscript",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A tiny JavaScript-compatible language layer with Jojo syntax and pipelines.",
   "license": "Unlicense",
   "type": "module",

package/src/compiler.js

@@ -20,6 +20,12 @@ import {
 
 import { transformMatchExpressions } from './match-parser.js'
 import { transformTypeAnnotations } from './type-annotations.js'
+import {
+  transformEffectDeclarations,
+  transformHandleBlocks,
+  findEffectDeclarations,
+  findHandleBlocks
+} from './effect-parser.js'
 
 /*
  * The auto-generated runtime import must use whatever name this package is
@@ -54,6 +60,18 @@ export function compile(source, options = {}) {
    */
   result = transformMatchExpressions(result)
 
+  /*
+   * Effects: `effect name(params)` declarations and `handle { ... } { ... }`
+   * blocks. Detected before either transform runs (both remove the source
+   * syntax they recognize), so the compiler knows afterwards whether the
+   * `defineEffect`/`withHandlers` runtime helpers need to be auto-imported.
+   */
+  const usesEffectDeclarations = findEffectDeclarations(result).length > 0
+  const usesHandleBlocks = findHandleBlocks(result).length > 0
+
+  result = transformEffectDeclarations(result)
+  result = transformHandleBlocks(result)
+
   /*
    * Jojo declarations.
    */
@@ -69,6 +87,18 @@ export function compile(source, options = {}) {
   const pipelineStdlibFunctions =
     findPipelineStdlibFunctions(result)
 
+  /*
+   * `effect`/`handle` syntax is never written by the user as a runtime
+   * function call, so their required runtime helpers are added explicitly,
+   * the same way `traceNode` is added below for `jojo profile`.
+   */
+  if (usesEffectDeclarations && !pipelineStdlibFunctions.includes('defineEffect')) {
+    pipelineStdlibFunctions.push('defineEffect')
+  }
+  if (usesHandleBlocks && !pipelineStdlibFunctions.includes('withHandlers')) {
+    pipelineStdlibFunctions.push('withHandlers')
+  }
+
   /*
    * `jojo profile` compiles with `{ profile: true }`, which wraps every
    * pipeline stage (and the initial source expression) in a call to the

package/src/effect-parser.js

@@ -0,0 +1,223 @@
+import { tokenize, significantTokens, maskNonCode } from './lexer.js'
+
+/*
+ * Algebraic effects / effect handlers, source-level syntax:
+ *
+ *   effect fetchUser(id)
+ *
+ *   handle {
+ *     fetchUser: id => http.get(`/users/${id}`)
+ *   } {
+ *     users |> map(user => fetchUser(user.id))
+ *   }
+ *
+ * Both constructs compile to plain calls into the `@panagos/jojoscript/runtime`
+ * effect runtime (`defineEffect`/`withHandlers`), following the same
+ * "regex/token transform, no real AST" philosophy as `match-parser.js` and
+ * `transforms.js` rather than introducing a parallel parsing architecture.
+ */
+
+function text(source, tokens) {
+  if (!tokens.length) return ''
+  return source.slice(tokens[0].start, tokens[tokens.length - 1].end)
+}
+
+/*
+ * Only applies `regex` to matches that are real code (not inside a string,
+ * template literal, or comment). Mirrors `transforms.js`'s private
+ * `codeAwareReplace` helper; duplicated here (rather than exported from
+ * `transforms.js`) to keep each transform module self-contained.
+ */
+function codeAwareReplace(source, regex, replacer) {
+  const mask = maskNonCode(source)
+
+  return source.replace(regex, (...args) => {
+    const match = args[0]
+    const offset = args[args.length - 2]
+
+    if (mask.slice(offset, offset + match.length) !== match) {
+      return match
+    }
+
+    return replacer(...args)
+  })
+}
+
+/*
+ * A deliberately simple, single-line declaration: `effect name(params)`,
+ * optionally `export`ed. Parameter names are plain identifiers (no default
+ * values/destructuring/nested parens) — enough to declare an effect's
+ * shape without needing a full expression parser.
+ */
+const EFFECT_DECLARATION = /^([ \t]*)(export\s+)?effect\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(([^()]*)\)\s*;?[ \t]*$/gm
+
+function splitParams(params) {
+  return params.trim() ? params.split(',').map(p => p.trim()).filter(Boolean) : []
+}
+
+/*
+ * Static scan for `effect name(params)` declarations. Used both by the
+ * compiler (to know which runtime imports are needed) and by pipeline
+ * inspection (`pipeline-ir.js`) to recognize effect names referenced from
+ * inside pipeline stages.
+ */
+export function findEffectDeclarations(source) {
+  const mask = maskNonCode(source)
+  const regex = new RegExp(EFFECT_DECLARATION.source, EFFECT_DECLARATION.flags)
+  const results = []
+  let match
+
+  while ((match = regex.exec(source))) {
+    const offset = match.index
+    if (mask.slice(offset, offset + match[0].length) !== match[0]) continue
+
+    results.push({
+      name: match[3],
+      params: splitParams(match[4]),
+      start: offset,
+      end: offset + match[0].length
+    })
+  }
+
+  return results
+}
+
+export function transformEffectDeclarations(source) {
+  return codeAwareReplace(source, EFFECT_DECLARATION, (match, indent, exportPart, name, params) => {
+    const paramList = JSON.stringify(splitParams(params))
+    return `${indent}${exportPart || ''}const ${name} = defineEffect(${JSON.stringify(name)}, ${paramList})`
+  })
+}
+
+/*
+ * Distinguishes the `handle` keyword from ordinary identifiers named
+ * "handle" (e.g. `stream.handle(...)`, `const handle = ...`).
+ */
+function isHandleKeyword(tokens, index) {
+  const token = tokens[index]
+  if (token.type !== 'identifier' || token.value !== 'handle') return false
+
+  const prev = tokens[index - 1]
+  if (prev && ['.', 'const', 'let', 'var', 'function', 'class'].includes(prev.value)) return false
+
+  const next = tokens[index + 1]
+  if (!next || next.value !== '{') return false
+
+  return true
+}
+
+function matchingBrace(tokens, openIndex) {
+  let depth = 0
+  for (let i = openIndex; i < tokens.length; i++) {
+    if (tokens[i].value === '{') depth++
+    else if (tokens[i].value === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  throw new SyntaxError('Unclosed `handle` block')
+}
+
+function splitTopLevelCommas(tokens) {
+  const result = []
+  let start = 0
+  let depth = 0
+
+  for (let i = 0; i < tokens.length; i++) {
+    const value = tokens[i].value
+    if (value === '(' || value === '[' || value === '{') depth++
+    else if (value === ')' || value === ']' || value === '}') depth--
+    else if (value === ',' && depth === 0) {
+      result.push(tokens.slice(start, i))
+      start = i + 1
+    }
+  }
+
+  if (start < tokens.length) result.push(tokens.slice(start))
+  return result
+}
+
+function extractHandlerNames(source, tokens) {
+  return splitTopLevelCommas(tokens)
+    .filter(group => group.length)
+    .map(group => {
+      const first = group[0]
+      if (first.type === 'identifier') return first.value
+      if (first.type === 'string') return first.value.slice(1, -1)
+      throw new SyntaxError(`Invalid handler entry in \`handle { ... }\`: ${text(source, group)}`)
+    })
+}
+
+function locateHandleBlock(tokens, index) {
+  const handlerOpen = index + 1
+  const handlerClose = matchingBrace(tokens, handlerOpen)
+
+  const bodyOpen = handlerClose + 1
+  if (!tokens[bodyOpen] || tokens[bodyOpen].value !== '{') {
+    throw new SyntaxError('`handle { ... }` must be followed by a body block: `handle { ... } { ... }`')
+  }
+  const bodyClose = matchingBrace(tokens, bodyOpen)
+
+  return { keywordIndex: index, handlerOpen, handlerClose, bodyOpen, bodyClose }
+}
+
+/*
+ * Static scan for every `handle { handlers } { body }` block in `source`,
+ * used both by the compiler and by pipeline inspection (which handler
+ * names are statically declared, for a best-effort "is this effect
+ * handled?" signal).
+ */
+export function findHandleBlocks(source) {
+  const tokens = significantTokens(tokenize(source))
+  const blocks = []
+
+  for (let i = 0; i < tokens.length; i++) {
+    if (!isHandleKeyword(tokens, i)) continue
+
+    const block = locateHandleBlock(tokens, i)
+    blocks.push({
+      start: tokens[block.keywordIndex].start,
+      end: tokens[block.bodyClose].end,
+      handlerNames: extractHandlerNames(source, tokens.slice(block.handlerOpen + 1, block.handlerClose))
+    })
+  }
+
+  return blocks
+}
+
+/*
+ * `handle { handlers } { body }` compiles to:
+ *
+ *   (await withHandlers({ handlers }, async () => { body }))
+ *
+ * Processes the rightmost (innermost, for nested `handle` blocks) match
+ * first on every iteration, same strategy as `transformMatchExpressions`,
+ * so nested handlers compile inside-out.
+ */
+export function transformHandleBlocks(source) {
+  let result = source
+
+  for (let iteration = 0; iteration < 1000; iteration++) {
+    const tokens = significantTokens(tokenize(result))
+
+    let target = null
+    for (let i = tokens.length - 1; i >= 0; i--) {
+      if (!isHandleKeyword(tokens, i)) continue
+      target = locateHandleBlock(tokens, i)
+      break
+    }
+
+    if (!target) return result
+
+    const handlerText = text(result, tokens.slice(target.handlerOpen, target.handlerClose + 1))
+    const bodyText = text(result, tokens.slice(target.bodyOpen, target.bodyClose + 1))
+    const replacement = `(await withHandlers(${handlerText}, async () => ${bodyText}))`
+
+    const start = tokens[target.keywordIndex].start
+    const end = tokens[target.bodyClose].end
+
+    result = result.slice(0, start) + replacement + result.slice(end)
+  }
+
+  throw new SyntaxError('handle transformation exceeded 1000 iterations')
+}

package/src/index.js

@@ -17,3 +17,17 @@ export {
 export {
   transformTypeAnnotations
 } from './type-annotations.js'
+
+export {
+  analyzePipelines,
+  buildGraph,
+  renderGraphText,
+  renderGraphDot
+} from './pipeline-ir.js'
+
+export {
+  transformEffectDeclarations,
+  transformHandleBlocks,
+  findEffectDeclarations,
+  findHandleBlocks
+} from './effect-parser.js'

package/src/pipeline-ir.js

@@ -1,5 +1,20 @@
 import { findAllPipelines } from './pipeline-parser.js'
 import { computePipelineId } from './pipeline-hash.js'
+import { findEffectDeclarations, findHandleBlocks } from './effect-parser.js'
+
+/*
+ * Best-effort, purely textual check for whether `effectName` is referenced
+ * anywhere in a stage's call (its name or its argument expressions), e.g.
+ * `map(user => fetchUser(user.id))` or a bare `saveUser` stage. This is
+ * static analysis over source text, not evaluation — it cannot tell
+ * whether the reference is actually reachable/called, only that the name
+ * appears with word boundaries.
+ */
+function effectsUsedByStage(stage, effectNames) {
+  if (!effectNames.length) return []
+  const haystack = stage.args.length ? `${stage.name} ${stage.args.join(' ')}` : stage.name
+  return effectNames.filter(name => new RegExp(`\\b${name}\\b`).test(haystack))
+}
 
 /*
  * Static, execution-free representation of a pipeline: SOURCE, one node per
@@ -8,8 +23,15 @@ import { computePipelineId } from './pipeline-hash.js'
  * `jojo profile`'s collected metrics via the same `node-<n>` id scheme the
  * compiler uses when emitting code (see `pipeline-parser.js`'s
  * `emitPipeline`).
+ *
+ * `options.effectNames`/`options.handledEffectNames` (both plain arrays of
+ * effect names) let callers surface effect usage per node (`jojo graph`
+ * passes the whole file's `effect name(...)` declarations and any
+ * statically-visible `handle { name: ... }` keys) — see `analyzePipelines`.
  */
-export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline)) {
+export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline), options = {}) {
+  const effectNames = options.effectNames ?? []
+  const handledEffectNames = new Set(options.handledEffectNames ?? [])
   const nodes = []
 
   nodes.push({
@@ -22,13 +44,15 @@ export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline)) {
   })
 
   pipeline.stages.forEach((stage, index) => {
+    const effects = effectsUsedByStage(stage, effectNames)
+
     nodes.push({
       id: `node-${index + 1}`,
       type: stage.name,
       label: stage.args.length ? `${stage.name}(${stage.args.join(', ')})` : stage.name,
       args: stage.args,
       dependencies: [`node-${index}`],
-      metadata: {}
+      metadata: effects.length ? { effects } : {}
     })
   })
 
@@ -42,15 +66,39 @@ export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline)) {
     metadata: {}
   })
 
-  return { id: pipelineId, expression: pipeline.expression.trim(), nodes }
+  /*
+   * Per-effect summary across the whole pipeline: name, which node(s)
+   * reference it, and a best-effort static "handled" signal — true only
+   * if a `handle { name: ... }` block naming this effect was found
+   * anywhere in the same file. A statically-declared handle block that is
+   * conditionally executed, or a handler installed dynamically at
+   * runtime, cannot be seen here; this is inspection, not proof.
+   */
+  const effects = nodes
+    .filter(node => node.metadata.effects?.length)
+    .flatMap(node => node.metadata.effects.map(name => ({
+      name,
+      nodeId: node.id,
+      staticallyHandled: handledEffectNames.has(name)
+    })))
+
+  return { id: pipelineId, expression: pipeline.expression.trim(), nodes, effects }
 }
 
 /*
  * Parses every pipeline statement in `source` and returns their graphs,
- * each with a deterministic id derived from its normalized structure.
+ * each with a deterministic id derived from its normalized structure. Also
+ * scans `source` for `effect name(...)` declarations and `handle { ... }`
+ * handler-map keys, so returned graphs can expose which effects each
+ * pipeline uses and whether a handler for them is statically visible.
  */
 export function analyzePipelines(source) {
-  return findAllPipelines(source).map(pipeline => buildGraph(pipeline))
+  const effectNames = findEffectDeclarations(source).map(declaration => declaration.name)
+  const handledEffectNames = findHandleBlocks(source).flatMap(block => block.handlerNames)
+
+  return findAllPipelines(source).map(pipeline =>
+    buildGraph(pipeline, undefined, { effectNames, handledEffectNames })
+  )
 }
 
 export function renderGraphText(graph) {
@@ -68,6 +116,10 @@ export function renderGraphText(graph) {
         : node.type.toUpperCase()
     }
 
+    if (node.metadata.effects?.length) {
+      label += `  [effects: ${node.metadata.effects.join(', ')}]`
+    }
+
     lines.push(label)
 
     if (index < graph.nodes.length - 1) {
@@ -83,9 +135,14 @@ export function renderGraphDot(graph) {
   const lines = ['digraph pipeline {']
 
   for (const node of graph.nodes) {
-    const dotLabel = node.args.length
+    let dotLabel = node.args.length
       ? `${node.type}\\n${node.args.join(', ').replace(/"/g, '\\"')}`
       : node.type
+
+    if (node.metadata.effects?.length) {
+      dotLabel += `\\n[effects: ${node.metadata.effects.join(', ')}]`
+    }
+
     lines.push(`  "${node.id}" [label="${dotLabel}"];`)
   }
 

package/src/runtime/collections.js

@@ -1,3 +1,5 @@
+import { getParallelHandler } from './effects.js'
+
 function iterable(value) {
   if (value == null) {
     throw new TypeError('Expected an iterable, got null or undefined')
@@ -141,9 +143,36 @@ async function* mapConcurrent(items, fn, concurrency) {
   }
 }
 
+/*
+ * A `PARALLEL` handler may be an ordinary sync function returning an
+ * array, an async function returning a Promise of an (async) iterable, or
+ * an async generator function returning an async iterable directly (no
+ * Promise wrapper at all). This normalizes all three into a single async
+ * iterable so `map()`'s return contract stays the same either way.
+ */
+async function* toAsyncIterable(resultOrPromise) {
+  const result = await resultOrPromise
+  for await (const item of result) yield item
+}
+
 export function map(items, fn) {
   if (isParallelTagged(items)) {
-    return mapConcurrent(items.source, fn, items[PARALLEL_TAG])
+    const concurrency = items[PARALLEL_TAG]
+    const handler = getParallelHandler()
+
+    /*
+     * `parallel(n)` is effect-backed: a `PARALLEL` handler installed via
+     * `handle { PARALLEL: ... } { ... }` decides how this actually runs
+     * (real concurrency, deterministic sequential execution, recorded
+     * scheduling, ...) instead of the default bounded-concurrency worker
+     * pool below. With no handler installed — the common case — behavior
+     * is exactly what it was before effects existed.
+     */
+    if (handler) {
+      return toAsyncIterable(handler({ items: items.source, fn, concurrency, meta: items.meta }))
+    }
+
+    return mapConcurrent(items.source, fn, concurrency)
   }
   return (function* () {
     let index = 0

package/src/runtime/effect-log.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/*
+ * Storage interface for recorded effect calls, mirroring
+ * `checkpoint-store.js`'s `CheckpointStore`: the record/replay handler
+ * wrappers in `effects.js` only ever talk to this interface, never to a
+ * filesystem/database directly, so alternative backends can be added later
+ * without touching the effect runtime.
+ */
+export class EffectLog {
+  async record(_call) {
+    throw new Error('EffectLog.record() is not implemented')
+  }
+
+  async replayNext(_name) {
+    throw new Error('EffectLog.replayNext() is not implemented')
+  }
+}
+
+/*
+ * In-memory log. `replayNext(name)` returns recorded calls for that effect
+ * name in the order they were recorded, one per call — the same effect
+ * invoked three times during recording replays its three results in order
+ * during replay, regardless of what other effects were interleaved.
+ */
+export class MemoryEffectLog extends EffectLog {
+  constructor(entries = []) {
+    super()
+    this.entries = [...entries]
+    this.cursor = new Map()
+  }
+
+  async record(call) {
+    this.entries.push(call)
+  }
+
+  async replayNext(name) {
+    const index = this.cursor.get(name) ?? 0
+    const matches = this.entries.filter(entry => entry.name === name)
+
+    if (index >= matches.length) {
+      throw new Error(`No recorded call left to replay for effect "${name}"`)
+    }
+
+    this.cursor.set(name, index + 1)
+    return matches[index]
+  }
+
+  toJSON() {
+    return this.entries
+  }
+}
+
+/*
+ * JSON-on-disk log, one file for the whole recording. Like
+ * `FileCheckpointStore`, writes go to a temp file first and are then
+ * renamed into place so a crash mid-write never corrupts the log.
+ */
+export class FileEffectLog extends EffectLog {
+  constructor(file) {
+    super()
+    this.file = file
+    this.entries = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : []
+    this.cursor = new Map()
+  }
+
+  async record(call) {
+    this.entries.push(call)
+
+    const dir = path.dirname(this.file)
+    fs.mkdirSync(dir, { recursive: true })
+
+    const tmp = `${this.file}.tmp-${process.pid}-${Date.now()}`
+    fs.writeFileSync(tmp, JSON.stringify(this.entries, null, 2))
+    fs.renameSync(tmp, this.file)
+  }
+
+  async replayNext(name) {
+    const index = this.cursor.get(name) ?? 0
+    const matches = this.entries.filter(entry => entry.name === name)
+
+    if (index >= matches.length) {
+      throw new Error(`No recorded call left to replay for effect "${name}"`)
+    }
+
+    this.cursor.set(name, index + 1)
+    return matches[index]
+  }
+}

package/src/runtime/effects.js

@@ -0,0 +1,263 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/*
+ * Algebraic effects / effect handlers runtime.
+ *
+ * The core idea: `defineEffect` turns a name into a callable that *describes
+ * an intent* ("perform fetchUser(42)") without deciding how it is carried
+ * out. `withHandlers` installs a handler map for the dynamic extent of a
+ * callback (an async-local, stack-shaped scope, exactly like
+ * `execution-context.js` already does for checkpoint/metrics state), and
+ * `performEffect` resolves an effect call against the innermost matching
+ * handler at the moment it is invoked.
+ *
+ * This is deliberately a *simplified* effect-handler model, not full
+ * algebraic effects: there is no delimited-continuation `resume`, handlers
+ * cannot resume a suspended computation more than once (or zero times) and
+ * inspect the result, and effects cannot be "re-thrown" to an outer handler
+ * after partial handling. What it *does* provide: named effects, dynamic
+ * handler dispatch, handler nesting/overriding, deterministic-vs-real
+ * handler swapping, and a clean async/JS interop story (a handler is just
+ * a normal — sync or async — JavaScript function).
+ */
+
+const handlerStorage = new AsyncLocalStorage()
+const invocationStorage = new AsyncLocalStorage()
+
+/*
+ * name -> { name, params, sideEffecting, replayable, builtin? }.
+ * Populated by every `defineEffect` call (i.e. every `effect name(...)`
+ * declaration compiles into one), plus the built-in `PARALLEL` capability.
+ * Purely descriptive metadata for inspection — never consulted by
+ * dispatch itself.
+ */
+const effectRegistry = new Map()
+
+export class UnhandledEffectError extends Error {
+  constructor(name) {
+    super(`Unhandled effect: ${name}\nNo handler registered for effect "${name}"`)
+    this.name = 'UnhandledEffectError'
+    this.effectName = name
+  }
+}
+
+export class EffectHandlerError extends Error {
+  constructor(name, cause) {
+    super(`Effect handler for "${name}" threw: ${cause?.message ?? cause}`, { cause })
+    this.name = 'EffectHandlerError'
+    this.effectName = name
+  }
+}
+
+export class RecursiveEffectError extends Error {
+  constructor(name) {
+    super(`Effect handler for "${name}" recursively invoked the same effect ("${name}")`)
+    this.name = 'RecursiveEffectError'
+    this.effectName = name
+  }
+}
+
+/*
+ * Declares a named effect and returns the callable used to *perform* it.
+ * `options.sideEffecting` (default true) and `options.replayable` (default
+ * false) are pure metadata consumed by inspection (`describeEffect`,
+ * `describeHandlers`) and by callers deciding whether it's safe to treat a
+ * result as reusable across a checkpoint/replay boundary — the runtime
+ * itself never enforces them.
+ */
+export function defineEffect(name, params = [], options = {}) {
+  effectRegistry.set(name, {
+    name,
+    params: [...params],
+    sideEffecting: options.sideEffecting ?? true,
+    replayable: options.replayable ?? false
+  })
+
+  function effectFn(...args) {
+    return performEffect(name, args)
+  }
+
+  effectFn.effectName = name
+  effectFn.isEffect = true
+  return effectFn
+}
+
+export function describeEffect(name) {
+  return effectRegistry.get(name) ?? null
+}
+
+export function listEffects() {
+  return [...effectRegistry.values()]
+}
+
+function normalizeHandlerEntry(name, value) {
+  if (typeof value === 'function') {
+    return { handle: value, deterministic: undefined }
+  }
+
+  if (value && typeof value === 'object' && typeof value.handle === 'function') {
+    return { handle: value.handle, deterministic: value.deterministic ?? undefined }
+  }
+
+  throw new TypeError(
+    `Invalid handler for effect "${name}": expected a function, e.g. \`id => fakeUser(id)\`, ` +
+    'or a `{ handle, deterministic }` descriptor'
+  )
+}
+
+function currentFrames() {
+  return handlerStorage.getStore() ?? []
+}
+
+/*
+ * Installs `handlers` (an object of `name -> handlerFn | { handle,
+ * deterministic }`) for the dynamic extent of `fn`, then restores whatever
+ * was active before. Nesting `withHandlers` calls (source: nested `handle`
+ * blocks) pushes a new innermost frame in front of the existing ones, so an
+ * inner handler for the same effect name shadows — overrides — an outer
+ * one, while effects the inner handler map does *not* mention still fall
+ * through to the outer handler.
+ *
+ * Caveat (shared with `execution-context.js`'s checkpoint/metrics context):
+ * because pipeline stages like `map`/`filter` are lazy generators, the
+ * handler frame is only active while `fn` is *synchronously/async-chain*
+ * executing. If `fn` merely constructs a lazy pipeline and returns it
+ * without consuming it (no `toArray`/`toArrayAsync`/`reduce`/...), items
+ * pulled later outside this call will see whatever handlers (if any) are
+ * active at that later point, not these ones. Always consume (or `await`)
+ * effectful pipelines inside the `handle { ... } { ... }` block itself.
+ */
+export function withHandlers(handlers, fn) {
+  if (!handlers || typeof handlers !== 'object') {
+    throw new TypeError('withHandlers requires a handler map object, e.g. { effectName: handlerFn }')
+  }
+
+  const normalized = {}
+  for (const [name, value] of Object.entries(handlers)) {
+    normalized[name] = normalizeHandlerEntry(name, value)
+  }
+
+  const frames = [{ handlers: normalized }, ...currentFrames()]
+  return handlerStorage.run(frames, fn)
+}
+
+/*
+ * Resolves and invokes the effect named `name` against the innermost
+ * handler that declares it. Always returns a Promise (even for a
+ * synchronous handler) so calling code never needs to know whether the
+ * active handler is sync or async — production (often async: HTTP/DB) and
+ * test (often sync: fake data) handlers are interchangeable.
+ */
+export async function performEffect(name, args) {
+  const inFlight = invocationStorage.getStore() ?? new Set()
+  if (inFlight.has(name)) {
+    throw new RecursiveEffectError(name)
+  }
+
+  const frame = currentFrames().find(f => name in f.handlers)
+  if (!frame) {
+    throw new UnhandledEffectError(name)
+  }
+
+  const entry = frame.handlers[name]
+  const nextInFlight = new Set(inFlight)
+  nextInFlight.add(name)
+
+  try {
+    return await invocationStorage.run(nextInFlight, () => entry.handle(...args))
+  } catch (error) {
+    if (error instanceof RecursiveEffectError || error instanceof UnhandledEffectError) throw error
+    throw new EffectHandlerError(name, error)
+  }
+}
+
+/*
+ * Introspection: which effects have an active handler *right now* (i.e.
+ * called from inside a `handle { ... } { ... }` block), and what is known
+ * about each — handled, whether the installed handler declared itself
+ * deterministic, and the declaring effect's `sideEffecting`/`replayable`
+ * metadata. Returns `[]` outside any `withHandlers` scope.
+ */
+export function describeHandlers() {
+  const seen = new Map()
+
+  for (const frame of currentFrames()) {
+    for (const [name, entry] of Object.entries(frame.handlers)) {
+      if (seen.has(name)) continue
+
+      const registryEntry = effectRegistry.get(name)
+      seen.set(name, {
+        name,
+        handled: true,
+        deterministic: entry.deterministic ?? null,
+        sideEffecting: registryEntry?.sideEffecting ?? null,
+        replayable: registryEntry?.replayable ?? null
+      })
+    }
+  }
+
+  return [...seen.values()]
+}
+
+/*
+ * `parallel(n)` as an effect-backed capability (see collections.js' `map`):
+ * if a `PARALLEL` handler is currently installed, it decides how
+ * `items |> parallel(n) |> map(fn)` actually runs (real concurrency,
+ * deterministic sequential execution, recorded scheduling, ...). With no
+ * handler installed, `map` falls back to the original bounded-concurrency
+ * implementation — existing programs that never touch `handle {}` are
+ * completely unaffected.
+ */
+effectRegistry.set('PARALLEL', {
+  name: 'PARALLEL',
+  params: ['concurrency'],
+  sideEffecting: true,
+  replayable: false,
+  builtin: true
+})
+
+export function getParallelHandler() {
+  const frame = currentFrames().find(f => 'PARALLEL' in f.handlers)
+  return frame ? frame.handlers.PARALLEL.handle : null
+}
+
+/*
+ * Record/replay extension point (see effect-log.js for the storage side).
+ * `recordHandlers` wraps a normal (typically production) handler map so
+ * every call's arguments and result are appended to `log`; `replayHandlers`
+ * builds a handler map that never runs real code at all, just replays
+ * recorded results for the given effect names, in call order, per effect.
+ */
+export function recordHandlers(handlers, log) {
+  const wrapped = {}
+
+  for (const [name, value] of Object.entries(handlers)) {
+    const entry = normalizeHandlerEntry(name, value)
+    wrapped[name] = {
+      deterministic: entry.deterministic,
+      handle: async (...args) => {
+        const result = await entry.handle(...args)
+        await log.record({ name, args, result, recordedAt: new Date().toISOString() })
+        return result
+      }
+    }
+  }
+
+  return wrapped
+}
+
+export function replayHandlers(effectNames, log) {
+  const wrapped = {}
+
+  for (const name of effectNames) {
+    wrapped[name] = {
+      deterministic: true,
+      handle: async () => {
+        const call = await log.replayNext(name)
+        return call.result
+      }
+    }
+  }
+
+  return wrapped
+}

package/src/runtime/index.js

@@ -48,4 +48,23 @@ export {
   getDefaultContext,
   resetDefaultContext
 } from './execution-context.js'
+export {
+  defineEffect,
+  withHandlers,
+  performEffect,
+  describeEffect,
+  listEffects,
+  describeHandlers,
+  getParallelHandler,
+  recordHandlers,
+  replayHandlers,
+  UnhandledEffectError,
+  EffectHandlerError,
+  RecursiveEffectError
+} from './effects.js'
+export {
+  EffectLog,
+  MemoryEffectLog,
+  FileEffectLog
+} from './effect-log.js'