Literate Execution

Joe Bond, Jacob Pake, Cristina David, Andrew McNutt, Trevor Sseguya Muwonge, Dominic Orchard, Roly Perera · 2026

Read Literate Execution by Joe Bond, Jacob Pake, Cristina David, Andrew McNutt, Trevor Sseguya Muwonge, Dominic Orchard, Roly Perera (2026) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2604-26967.txt.

Introduction

Bond and six colleagues propose literate execution, inverting the literate programming idea where code sits inside a static narrative. Here docs and other explanatory bits become first-class artefacts, computed alongside a running program and woven into a view of its execution. They explore the idea through Fluid, a language whose provenance runtime records fine-grained links between inputs and outputs. Those links surface as interactions letting readers trace how middle values shape a result. Merging pictures, provenance, and exposition aims to make programs more explorable and clear.

Catalog record

CREATORJoe Bond, Jacob Pake, Cristina David, Andrew McNutt, Trevor Sseguya Muwonge, Dominic Orchard, Roly Perera
YEAR2026
COLLECTIONPAPERS
FORMATTXT
FILE SIZE447736
LICENSEhttp://creativecommons.org/licenses/by/4.0/
RIGHTSCC BY
SOURCEarXiv

Source: https://arxiv.org/abs/2604.26967

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

Literate Execution Joe Bond, Jacob Pake, Cristina David, Andrew McNutt, Trevor Sseguya Muwonge, Dominic Orchard, Roly Perera Abstract . Literate programming , introduced by 17 , interleaves code and prose so that a program can be read as both executable and explanatory text. We propose literate execution , which inverts this relationship: rather than embedding code within a static narrative, we treat documentation — and other expository elements such as visualisations — as first-class artefacts that can be computed alongside a running program and then integrated into a view of its execution. We explore this idea through Fluid, a programming language with a provenance-tracking runtime that records fine-grained dependencies between inputs and outputs. These provenance relationships can be surfaced as interactions that allow readers to explore how intermediate values contribute to a result. By integrating visualisation, provenance, and exposition, literate execution aims to make programs more explorable and self-explanatory, and explorable explanations easier to program. \plateauConference [PLATEAU ’26]16March 9–10, 2025Pittsburgh, PA, USA \setcopyright none \acmDOI \settopmatter printacmref=false \orcid 0009-0008-5995-6994 \orcid 0009-0001-3568-5383 \orcid 0000-0002-9106-934X \orcid 0000-0001-8255-4258 \orcid 0009-0007-3294-9172 \orcid 0000-0002-7058-7842 \orcid 0000-0001-9249-9862 1. From Literate Programming to Literate Execution Data-driven documents, such as scientific papers and policy reports, typically present their findings without exposing how those findings were produced. A reader who encounters a statistic or a chart has no way to interrogate what went into it, or how it relates to the underlying data. The document is opaque : one sees the output of a computation, but not the computation itself. There are various ways one might approach the challenge of making documents like these more transparent. Explorable explanations , popularised by 40 and venues such as distill.pub and VISxAI 13 , invite readers to adjust parameters and see how results change, exploring how the computation would behave under different inputs or assumptions. We call this counterfactual transparency; multiverse analyses 36 ; 8 pursue a similar idea in the context of statistical reporting. But consider a report such as the IPCC’s Summary for Policymakers 14 . A policymaker reading it might want to understand not only how results would differ under different assumptions, but also how the reported conclusions for a given set of assumptions follow from the data: what were the intermediate aggregation steps, and which parts of the input contributed to a particular summary statistic? We call these sorts of concerns decompositional transparency. It has two axes: sequential decomposition reveals the intermediate artefacts that arose during the computation, while parallel decomposition reveals which parts of the input influenced which parts of the output. In this paper we argue that decompositional transparency is also an important facet of transparency, and one largely unaddressed by existing tools. Creating transparent documents of any kind is genuinely hard. Some of the difficulty is what 3 would call essential : choosing what to explain, how to structure a narrative, and which interactions will be pedagogically effective requires communicative skill that cannot be engineered away. But alongside this essential difficulty, there is a large component of accidental complexity. Authoring systems such as Idyll 6 and Living Papers 12 have provided valuable infrastructure for supporting counterfactual transparency, reducing the effort needed to create explorable, parameter-driven documents. Yet making a computation’s internal structure transparent remains largely a manual undertaking: the author must build bespoke interactive presentations that reimagine, and to some extent reimplement, aspects of the computation for the purpose of explanation. This accidental complexity is closely related to a familiar problem in software engineering: understanding why a program produced a given output, by inspecting intermediate states and tracing dependencies, is the essence of debugging. The tools and techniques that support decompositional transparency for end-users and those that support debugging for developers address fundamentally the same problem. In this paper we propose literate execution , an approach that provides infrastructure for decompositional transparency. Rather than asking authors to build bespoke interactive presentations, we embed documentation directly into the execution of a program, so that the program’s own dependency structure can generate interactions automatically. The name reflects a structural parallel with literate programming 17 , which interleaves prose with static source code to make programs readable. Literate execution applies the same principle to a dynamic rather than static object: it interleaves prose with the execution, making the computation, not just the program, a literate artefact. Figure 1 . This work extends our prior work 25 ; 2 on automatic visualisation of dependencies by introducing ‘doc comments’ and intermediate value exploration to facilitate literate execution . Here we show how these new features can be used to explain matrix convolution. We explore this idea using a programming language called Fluid ( http://f.luid.org ) which has built-in dependency tracking 25 ; 2 . In Fluid, every computation produces a dynamic dependence graph (DDG) alongside the computed output, capturing fine-grained dependencies between outputs and inputs. This provenance information can then be made available to end-users via additional interactions, making it possible to point at computed content and see, in situ (for example on a web page hosting visualisations or text authored in Fluid), how parts of the input contributed to various parts of the output. Figure 1 shows how a purely functional implementation of matrix convolution in Fluid, an algorithm used in machine learning and image processing, can be turned into an interactive figure automatically. This paper introduces two new Fluid features for authoring transparent computational documents. First, dynamically computed doc comments , possibly containing embedded visualisations, can be attached to runtime values using a special decorator notation. Second, a UI for exploring intermediate values that allows a user to interactively inspect them and trace their upstream and downstream dependencies. We call the combination of these two features into a document authoring tool literate execution . Alongside these features we also present a new, Python-like surface syntax for Fluid, reflecting our target audience of data scientists and domain experts accustomed to Python. Specifically, we contribute literate execution as a paradigm, which we describe through motivating examples in § 2 . To support this work, we contribute new syntax and semantics for doc comments in Fluid, and describe informally how literate execution views are derived from the dynamic dependence graph for a program (§ 3 ). Finally, we reflect on the current state of play of our design and identify directions for future work in § 4 . Through this work, we aim to lower the barrier for authors to create transparent computational artefacts, making it easier to communicate complex computational ideas through interactive documents. 2. Motivating Examples Traditional literate programming interleaves static code with natural language commentary. Literate execution inverts things, embedding the natural language commentary into the program’s execution, so the program itself participates in its own explanation. We illustrate this with two examples, first describing each from the reader’s perspective (§2.1), then the Fluid mechanisms that support these interactions (§2.2). 2.1. Two Reader Experiences Example 1: Matrix convolution. Figure 1 shows a 5 \times 5 input image and a 3 \times 3 filter (A) producing a 5 \times 5 output via convolution. The reader starts by seeing these three matrices. Clicking on an output cell establishes a persistent selection (B), highlighting in green both the cell and the

Read the complete text