Skip to content

Commit 10f3cc8

Browse files
committed
♻️ Hand a REPL entry's computed root data back on its own result (#939)
The per-binding publication protocol #939 shipped is removed whole: no producer, mode, admission field, parser, counter, outcome marker or expansion plumbing, and nothing renamed in its place. `expand.ts`, `generated-xmd.ts`, `host.ts` and the CLI's `entries.ts` return to the pre-#939 base byte for byte. In its place, an execution computes the root data it hands back. A binding is a byproduct of running the document, so one private owner per canonical invocation is given the actual root environment by identity, and at the result boundary it reads that root's current eligible data onto the ordinary `DocumentResult` — on an authored failure as well as on success, because a failure is an outcome. The journal gains no operation, and `parseDocumentResult` stays the single interpretation point, so a cold reader answers from the record it already parses. Reading is owned the same way. `useSecretDetection` now returns the disclosure policy beside the journal gate, so the owned read closes over the exact scanner the gate closes over and a later same-name Context cannot weaken it. `HostExecution.bindings()` exposes that read, and `ReplSession.bindings()` layers it over the retained head, rechecking the running entry's identity after the read suspends. Ordinary authored failures now normalize inside the canonical result boundary. Before this, a plain `<Fail>` left no `DocumentResult` at all — the root Close held the durable protocol's serialized error — so its rendered text was lost to every later reader. Durability and fatal Files failures still escape ahead of it.
1 parent 7490f01 commit 10f3cc8

21 files changed

Lines changed: 1318 additions & 1633 deletions

‎architecture.md‎

Lines changed: 49 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -6155,53 +6155,57 @@ ordinarily mutable inside the execution that receives them. The REPL derives
61556155
that record only from values durably retained before the new entry's admission,
61566156
so replay derives the identical record from the identical bytes.
61576157

6158-
#### Execution owns which captures it retains
6158+
#### Execution computes the root data its result hands back
61596159

61606160
An `eval` block's exports are journaled because evaluating one is a durable
6161-
effect. A root `<Let>` and an ordinary component capture are not, which is
6162-
right for a document that runs once and wrong for one entry of several over one
6163-
journal — so retention is a second trusted-host input beside the initial
6164-
bindings, stated once per execution as `rootBindingPublications: "json-v1"`,
6165-
and read nowhere else. Ordinary execution states nothing and behaves exactly as
6166-
it did.
6167-
6168-
The publisher is **execution-owned**, not described: Core builds it beside the
6169-
canonical root binding environment, holds that exact environment in its
6170-
closure, and hands it to expansion as an argument beside the import terminal
6171-
and the generated-root owner. What may publish is therefore a capture whose
6172-
actual assignment target is that object — an identity rather than a judgment
6173-
about a file name, a coroutine or a source position. A component body, an
6174-
`<Each>` iteration, a `<Spawn>` and a generated fragment each write a different
6175-
environment and none of them acquires root ownership from where it was written.
6176-
It is not a member of `ExecutionEnvironment`, which describes what a document
6177-
is expanded *against*; it reaches no Context, Api or registry, and it expires
6178-
with the execution.
6179-
6180-
The retained profile is part of the history's identity. The mode travels on the
6181-
root import's own description under a namespaced field, and root-history
6182-
admission compares the recorded mode against the invoking one before a recorded
6183-
terminal is reused, before public replay policy and before authored work — so
6184-
an execution cannot publish into the middle of a sequence its own records do
6185-
not account for. An absent field is a readable history written before this
6186-
existed: it agrees with an execution that publishes nothing, which is what lets
6187-
an unfinished entry from such a file be continued in its own mode through its
6188-
own close, with its completed effects restored rather than repeated. Any other
6189-
value, and any disagreement, is refused. Cold projection applies that same rule
6190-
independently, off the admission each segment begins with, so a cold command
6191-
and a live session cannot disagree about whose a retained capture is.
6192-
6193-
One record per successful root capture, whichever outcome it carries, so the
6194-
retained effect sequence is a fact about the document rather than about what
6195-
happened to be serializable. The value crossing is a detached snapshot taken
6196-
through the one strict JSON parser the initial bindings are copied through; the
6197-
binding itself stays the exact value the producer made, so same-entry
6198-
reference identity, resource lifetime and later mutation are unchanged and none
6199-
of them reaches the record. A value outside that domain takes a value-free
6200-
outcome, which publishes nothing, removes nothing and keeps the last value
6201-
anything did publish under that name. The publication goes through the ordinary
6202-
durable path, so the secret gate and the append fence apply to it as they do to
6203-
every other effect: a rejected publication binds nothing, writes no sentinel
6204-
and keeps its own fatal classification.
6161+
effect. A root `<Let>` and an ordinary component capture are not, and nothing
6162+
here makes them one. A binding is a **byproduct of running the document**: the
6163+
thing a later execution over the same journal needs is not a record per
6164+
capture but the root as it stood when the document finished — which is already
6165+
a fact the canonical result is the place for. So the execution computes that
6166+
data at its own result boundary and carries it on the ordinary
6167+
`DocumentResult`, under an optional member. The journal gains no operation, no
6168+
name, no sequence and no mode; ordinary execution behaves exactly as it did,
6169+
and LET11's inventory is unchanged.
6170+
6171+
Two consequences follow from putting it there rather than beside it. A cold
6172+
reader answers from the record it already parses, so `parseDocumentResult`
6173+
stays the single interpretation point for live and replayed results alike. And
6174+
an ordinary authored failure carries its data too, because a failure is an
6175+
outcome with a result — which is why that normalization happens inside the
6176+
canonical boundary, with durability and fatal Files failures still escaping
6177+
ahead of it.
6178+
6179+
The owner is **execution-owned**, not described: Core creates one private owner
6180+
per canonical invocation, adopts the disclosure policy where the secret
6181+
detection that gates the journal is established, and is handed the actual root
6182+
binding environment by identity where expansion creates it. What it reads is
6183+
therefore that exact object — an identity, rather than a judgment about a file
6184+
name, a coroutine or a source position. A component body, an `<Each>` iteration
6185+
and a `<Spawn>` each write an environment of their own, so their local names
6186+
are not the root's; a root `<Each as>` aggregate is written at the root and so
6187+
is root data. The owner is not a member of `ExecutionEnvironment`, which
6188+
describes what a document is expanded *against*; it reaches no Context, Api or
6189+
registry, and it expires with the execution.
6190+
6191+
Eligibility is a property of the data, not of its provenance. Every own member
6192+
of that root whose name is a valid binding name and whose value is whole in the
6193+
strict JSON domain is in, except `props`, which each execution validates for
6194+
itself. Anything else is omitted — and omission carries no value, names no
6195+
type and removes nothing. There is deliberately no assignment, capture or
6196+
version ledger: "own root data" means membership of that environment, which is
6197+
why a name an entry inherited and then mutated is part of what its result
6198+
carries without being named again, and why a transient value overwritten
6199+
before the result is not recoverable as history.
6200+
6201+
Reading is owned the same way. `HostExecution.bindings()` is a host-only read
6202+
that authorizes nothing, and it answers through the disclosure policy the owner
6203+
adopted — the exact scanner the journal gate closed over, not a replaceable
6204+
Context — so a counterfeit same-name policy installed afterwards cannot weaken
6205+
it and a secret refuses the read whole rather than appearing in it. The REPL
6206+
session layers that live read over the retained head and rechecks the running
6207+
entry's identity after the read suspends, so one entry's live values are never
6208+
credited to another.
62056209

62066210
The session owns at most one entry task. Starting another needs two separate
62076211
facts — the preceding entry has a retained terminal close, *and* its task has

‎packages/cli/src/documents/sidekick/bindings.md‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -32,23 +32,25 @@ Sidekick responses, and the root bindings a REPL entry inherits.
3232
entry needs from an earlier one is reached by name inside the entry, not
3333
carried through your response.
3434
- Inside an entry, a root `<Let as="name" value={...} />` and a root component
35-
capture are published for the entries after it, alongside an `eval` block's
36-
exports. For each name the value that crosses is whichever of them published
37-
last.
35+
capture reach the entries after it, alongside an `eval` block's exports. What
36+
an entry hands on is the state its root is in when it finishes, so the order
37+
the names were written in does not matter — only what they were at the end.
3838
- What crosses is ordinary JSON: text, numbers, `true`, `false`, `null`, lists
3939
and plain objects of those. A function, a live handle, a class instance, a
4040
cycle, a non-finite number and `undefined` stay in the entry that made them.
41-
They are usable for the rest of that entry and are not published.
42-
- A capture like that publishes no replacement, so the name keeps the last
43-
value anything did publish under it. After an entry publishes `saved =
44-
"alpha"`, a later entry binding a function as `saved` uses that function and
45-
leaves `saved` as `"alpha"` for the entry after it. A name only ever bound to
46-
such a value is absent from `<REPL.Bindings />` entirely.
47-
- The published value is a copy taken when the capture happened. Mutating the
48-
object afterwards changes the entry's own binding and nothing a later entry
49-
reads; publish it again to publish the change.
50-
- A history written before captures were published is read as it is: a value it
51-
never recorded stays absent, and nothing re-runs the entry to recover it.
41+
They are usable for the rest of that entry and do not cross.
42+
- A name bound only to a value like that is absent rather than cleared, so the
43+
name keeps whichever value an entry last handed on. After an entry hands on
44+
`saved = "alpha"`, a later entry binding a function as `saved` uses that
45+
function and leaves `saved` as `"alpha"` for the entry after it. A name only
46+
ever bound to such a value is absent from `<REPL.Bindings />` entirely.
47+
- Because it is the state at the end, a change an entry makes to a value before
48+
it finishes is part of what it hands on — including to a value it inherited
49+
and never named again. A change made after an entry finished reaches nothing.
50+
- An entry that failed still hands on the state it had. One whose cancellation
51+
the file records hands on nothing, and so does one still running.
52+
- A history written before this was retained is read as it is: a value it never
53+
recorded stays absent, and nothing re-runs the entry to recover it.
5254

5355
## Example
5456

@@ -66,10 +68,10 @@ in your next response. Feedback is information to reason about, not an automatic
6668
variable. The name can be referenced inside an entry that inherits that
6769
binding, or restated in your response with an explicit `Let`.
6870

69-
A second one: a name missing from `<REPL.Bindings />` is a name nothing
70-
published, not a name something removed. There is no way to delete a published
71-
value — write an entry that publishes the value you want under that name
72-
instead of expecting an absence to clear it.
71+
A second one: a name missing from `<REPL.Bindings />` is a name nothing handed
72+
on, not a name something removed. There is no way to delete a retained value —
73+
write an entry that ends with the value you want under that name instead of
74+
expecting an absence to clear it.
7375

7476
## Read next
7577

‎packages/cli/src/repl/entries.ts‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,7 @@ import type { DurableEvent, DurableStream, Yield } from "@executablemd/durable-s
3737
export const ROOT_IMPORT = "__root__";
3838

3939
/** The coroutine an entry's root document runs on. */
40-
/**
41-
* The coroutine an entry's own root document runs on.
42-
*
43-
* Exported because the projection beside this reads it too: a retained root
44-
* capture belongs to the entry's root, and a record that names some other
45-
* coroutine is not something either half of this reader may own.
46-
*/
47-
export const ROOT_COROUTINE = "root";
40+
const ROOT_COROUTINE = "root";
4841

4942
/** What the REPL could not read or write about an entry boundary. */
5043
export class ReplSegmentError extends Error {

0 commit comments

Comments
 (0)