rose-ash/sx/sx/essays/continuations.sx

(defcomp ~essays/continuations/essay-continuations ()
  (~docs/page :title "Continuations and call/cc"  (p :class "text-stone-500 text-sm italic mb-8"    "Delimited continuations in SX — what shift/reset enables on both the server (Python) and client (JavaScript).")  (~docs/section :title "What is a continuation?" :id "what"    (p :class "text-stone-600"      "A continuation is the rest of a computation. At any point during evaluation, the continuation is everything that would happen next. call/cc (call-with-current-continuation) captures that \"rest of the computation\" as a first-class function that you can store, pass around, and invoke later — possibly multiple times.")    (~docs/code :lang "lisp" :code      ";; call/cc captures \"what happens next\" as k\n(+ 1 (call/cc (fn (k)\n  (k 41))))  ;; → 42\n\n;; k is \"add 1 to this and return it\"\n;; (k 41) jumps back to that point with 41")    (p :class "text-stone-600"      "The key property: invoking a continuation abandons the current computation and resumes from where the continuation was captured. It is a controlled, first-class goto."))  (~docs/section :title "Server-side: suspendable rendering" :id "server"    (p :class "text-stone-600"      "The strongest case for continuations on the server is suspendable rendering — the ability for a component to pause mid-render while waiting for data, then resume exactly where it left off.")    (~docs/code :lang "lisp" :code      ";; Hypothetical: component suspends at a data boundary\n(defcomp ~essays/continuations/user-profile (&key user-id)\n  (let ((user (suspend (query :user user-id))))\n    (div :class \"p-4\"\n      (h2 (get user \"name\"))\n      (p (get user \"bio\")))))")    (p :class "text-stone-600"      "Today, all data must be fetched before render_to_sx is called — Python awaits every query, assembles a complete data dict, then passes it to the evaluator. With continuations, the evaluator could yield at (suspend ...), the server flushes what it has so far, and resumes when the data arrives. This is React Suspense, but for server-side s-expressions.")    (p :class "text-stone-600"      "Streaming follows naturally. The server renders the page shell immediately, captures continuations at slow data boundaries, and flushes partial SX responses as each resolves. The client receives a stream of s-expression chunks and incrementally builds the DOM.")    (p :class "text-stone-600"      "Error boundaries also become first-class. Capture a continuation at a component boundary. If any child fails, invoke the continuation with fallback content instead of letting the exception propagate up through Python. The evaluator handles it, not the host language."))  (~docs/section :title "Client-side: linear async flows" :id "client"    (p :class "text-stone-600"      "On the client, continuations eliminate callback nesting for interactive flows. A confirmation dialog becomes a synchronous-looking expression:")    (~docs/code :lang "lisp" :code      "(let ((answer (call/cc show-confirm-dialog)))\n  (if answer\n    (delete-item item-id)\n    (noop)))")    (p :class "text-stone-600"      "show-confirm-dialog receives the continuation, renders a modal, and wires the Yes/No buttons to invoke the continuation with true or false. The let binding reads top-to-bottom. No promises, no callbacks, no state machine.")    (p :class "text-stone-600"      "Multi-step forms — wizard-style UIs where each step captures a continuation. The back button literally invokes a saved continuation, restoring the exact evaluation state:")    (~docs/code :lang "lisp" :code      "(define wizard\n  (fn ()\n    (let* ((name  (call/cc (fn (k) (render-step-1 k))))\n           (email (call/cc (fn (k) (render-step-2 k name))))\n           (plan  (call/cc (fn (k) (render-step-3 k name email)))))\n      (submit-registration name email plan))))")    (p :class "text-stone-600"      "Each render-step-N shows a form and wires the \"Next\" button to invoke k with the form value. The \"Back\" button invokes the previous step\'s continuation. The wizard logic is a straight-line let* binding, not a state machine."))  (~docs/section :title "Cooperative scheduling" :id "scheduling"    (p :class "text-stone-600"      "Delimited continuations (shift/reset rather than full call/cc) enable cooperative multitasking within the evaluator. A long render can yield control:")    (~docs/code :lang "lisp" :code      ";; Render a large list, yielding every 100 items\n(define render-chunk\n  (fn (items n)\n    (when (> n 100)\n      (yield)  ;; delimited continuation — suspends, resumes next frame\n      (set! n 0))\n    (when (not (empty? items))\n      (render-item (first items))\n      (render-chunk (rest items) (+ n 1)))))")    (p :class "text-stone-600"      "This is cooperative concurrency without threads, without promises, without requestAnimationFrame callbacks. The evaluator's trampoline loop already has the right shape — it just needs to be able to park a thunk and resume it later instead of immediately."))  (~docs/section :title "Undo as continuation" :id "undo"    (p :class "text-stone-600"      "If you capture a continuation before a state mutation, the continuation IS the undo operation. Invoking it restores the computation to exactly the state it was in before the mutation happened.")    (~docs/code :lang "lisp" :code      "(define with-undo\n  (fn (action)\n    (let ((restore (call/cc (fn (k) k))))\n      (action)\n      restore)))\n\n;; Usage:\n(let ((undo (with-undo (fn () (delete-item 42)))))\n  ;; later...\n  (undo \"anything\"))  ;; item 42 is back")    (p :class "text-stone-600"      "No command pattern, no reverse operations, no state snapshots. The continuation captures the entire computation state. This is the most elegant undo mechanism possible — and the most expensive in memory, which is the trade-off."))  (~docs/section :title "Implementation" :id "implementation"    (p :class "text-stone-600"      "Delimited continuations via shift/reset are implemented as an optional extension module across all SX evaluators — the hand-written Python evaluator, the transpiled reference evaluator, and the JavaScript bootstrapper output. They are compiled in via " (code "--extensions continuations") " — without the flag, " (code "reset") " and " (code "shift") " are not in the dispatch chain and will error if called. The implementation uses exception-based capture with re-evaluation:")    (~docs/code :lang "lisp" :code      ";; reset establishes a delimiter\n;; shift captures the continuation to the nearest reset\n\n;; Basic: abort to the boundary\n(reset (+ 1 (shift k 42)))  ;; → 42\n\n;; Invoke once: resume with a value\n(reset (+ 1 (shift k (k 10))))  ;; → 11\n\n;; Invoke twice: continuation is reusable\n(reset (* 2 (shift k (+ (k 1) (k 10)))))  ;; → 24\n\n;; Map over a continuation\n(reset (+ 10 (shift k (map k (list 1 2 3)))))  ;; → (11 12 13)\n\n;; continuation? predicate\n(reset (shift k (continuation? k)))  ;; → true")    (p :class "text-stone-600"      "The mechanism: " (code "reset") " wraps its body in a try/catch for " (code "ShiftSignal") ". When " (code "shift") " executes, it raises the signal — unwinding the stack to the nearest " (code "reset") ". The reset handler constructs a " (code "Continuation") " object that, when called, pushes a resume value onto a stack and re-evaluates the entire reset body. On re-evaluation, " (code "shift") " checks the resume stack and returns the value instead of raising.")    (p :class "text-stone-600"      "This is the simplest correct implementation for a tree-walking interpreter. Side effects inside the reset body re-execute on continuation invocation — this is documented behaviour, not a bug. Pure code produces correct results unconditionally.")    (p :class "text-stone-600"      "Shift/reset are strictly less powerful than full call/cc but cover the practical use cases — suspense, cooperative scheduling, early return, value transformation — without the footguns of capturing continuations across async boundaries or re-entering completed computations.")    (p :class "text-stone-600"      "Full call/cc is specified in " (a :href "/sx/(language.(spec.callcc))" :class "text-violet-600 hover:underline" "callcc.sx") " for targets where it's natural (Scheme, Haskell). The evaluator is already continuation-passing-style-adjacent — the thunk IS a continuation, just one that's always immediately invoked. Making it first-class means letting user code hold a reference to it.")    (p :class "text-stone-600"      "The key insight: having the primitive available doesn't make the evaluator harder to reason about. Only code that calls shift/reset pays the complexity cost. Components that don't use continuations behave exactly as they do today.")    (p :class "text-stone-600"      "In fact, continuations are easier to reason about than the hacks people build to avoid them. Without continuations, you get callback pyramids, state machines with explicit transition tables, command pattern undo stacks, Promise chains, manual CPS transforms, and framework-specific hooks like React's useEffect/useSuspense/useTransition. Each is a partial, ad-hoc reinvention of continuations — with its own rules, edge cases, and leaky abstractions.")    (p :class "text-stone-600"      "The complexity doesn't disappear when you remove continuations from a language. It moves into user code, where it's harder to get right and harder to compose."))  (~docs/section :title "What this means for SX" :id "meaning"    (p :class "text-stone-600"      "SX started as a rendering language. TCO made it capable of arbitrary recursion. Macros made it extensible. Delimited continuations make it a full computational substrate — a language where control flow itself is a first-class value.")    (p :class "text-stone-600"      "The practical benefits are real: streaming server rendering, linear client-side interaction flows, cooperative scheduling, and elegant undo. These aren't theoretical — they're patterns that React, Clojure, and Scheme have proven work.")    (p :class "text-stone-600"      "Shift/reset is implemented and tested across Python and JavaScript as an optional extension. The same specification in " (a :href "/sx/(language.(spec.continuations))" :class "text-violet-600 hover:underline" "continuations.sx") " drives both bootstrappers. One spec, every target, same semantics — compiled in when you want it, absent when you don't."))))