Skip to content

Commit babfb6f

Browse files
committed
🚨 Own the binding handle with a resource, and detach every read (#939)
Repairs the five findings both exact-head reviews returned on 10f3cc8, which stays as it was. The owner is now an Effection resource, acquired in the canonical invocation's own scope before the work it holds anything for, so its finalizer is established before there is a live reference to release. It releases the document's root environment and this execution's scanner on its own teardown, whichever way the run ends, and a run halted or fatally failed before it settled has nothing to read and no live environment to read instead. The manually paired `release()` is gone. Settling keeps the accepted data and lets go of the root and the scanner. What arrives there came back through the root's own close, so the gate that decides what may be written has already vetted it — which is what lets the handle stay readable for its promised lifetime without holding a live reference open to serve a read, and what keeps a replayed run from scanning its own journal again. Every successful read is copied rather than shared, live or settled. Two reads of one settled execution are two graphs, so a reader cannot edit an outcome the journal has already recorded. A fragment expands against the containing document's environment, as it always has, so a name it binds with `as` is written in that execution's root and is eligible there. The earlier premise that it writes an environment of its own was wrong; a generated root is the separate case. Released fragment semantics are unchanged and nothing tracks provenance. Completes two frozen observations that were claimed but not exercised: a bound command's outcome crossing to a successor by its three channels, and a transient JSON value overwritten by a function before anything retained it, absent from the result, the next entry and a cold reading. Cancellation carries no computed map of its own and does not unretain the facts recorded before it. Its representative is now the real unfinished question prefix with a cancellation recorded on a copy of it, and the guide and spec say that distinction instead of "hands on nothing".
1 parent 10f3cc8 commit babfb6f

7 files changed

Lines changed: 248 additions & 105 deletions

File tree

‎architecture.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4111,7 +4111,9 @@ Glob keeps its existing required `include`, optional `exclude` and value-returni
41114111
contract. With `as` it binds a sorted, deduplicated array of relative file paths
41124112
and renders no text. Generated evaluation supports ordinary fragment-local
41134113
bindings, structural constructs, declarative expression props over those
4114-
bindings, and pure components. It imports no caller bindings and exports none.
4114+
bindings, and pure components. It reads no caller binding and has no export or
4115+
result channel of its own; a name it binds with `as` is written in the
4116+
containing document's environment, which is the one it expands against.
41154117
Executable fences,
41164118
imports and effectful components outside the selected permission remain refused.
41174119

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,10 @@ Sidekick responses, and the root bindings a REPL entry inherits.
4848
it finishes is part of what it hands on — including to a value it inherited
4949
and never named again. A change made after an entry finished reaches nothing.
5050
- 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.
51+
the file records hands on no state of its own — but it does not take back
52+
what it had already recorded before then, so an `eval` export it made is
53+
still there for the entry after it. One still running has handed on nothing
54+
yet.
5255
- A history written before this was retained is read as it is: a value it never
5356
recorded stays absent, and nothing re-runs the entry to recover it.
5457

‎packages/cli/tests/repl-entries.test.ts‎

Lines changed: 112 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,18 @@ function cancelled(coroutineId: string): DurableEvent {
319319
return { type: "close", coroutineId, result: { status: "cancelled" } };
320320
}
321321

322+
/**
323+
* A private copy of one unfinished prefix, with a cancellation recorded for it.
324+
*
325+
* Appended rather than substituted, because that is the shape this records: an
326+
* entry that really stopped unfinished and whose cancellation the file then
327+
* notes. Copied, so the prefix these bytes came from is not the prefix this
328+
* reading is taken from, and the original can be compared afterwards.
329+
*/
330+
function cancelledAfter(prefix: readonly DurableEvent[]): DurableEvent[] {
331+
return [...prefix.map((event) => event), cancelled("root")];
332+
}
333+
322334
/** The same journal with the close of one entry replaced. */
323335
function withClose(
324336
events: readonly DurableEvent[],
@@ -4073,6 +4085,13 @@ const CAPTURES = [
40734085
"",
40744086
'<Reading as="functionJson" />',
40754087
"",
4088+
// The one capture whose value the engine composes rather than a component:
4089+
// a bound command's outcome is a root binding like any other, so what the
4090+
// next entry reads is the three channels this process settled to.
4091+
'```bash exec as="ran"',
4092+
"printf ready; printf noted >&2",
4093+
"```",
4094+
"",
40764095
"Captured.",
40774096
"",
40784097
].join("\n");
@@ -4087,6 +4106,7 @@ const READS_CAPTURES = [
40874106
' markdownText.includes("Plan"),',
40884107
" markdownValue.steps,",
40894108
" functionJson.pressure,",
4109+
" `${ran.exitCode}:${ran.stdout}:${ran.stderr}`,",
40904110
'].join("/");',
40914111
"```",
40924112
"",
@@ -4112,12 +4132,19 @@ describe("REPL entries: the root values a capture retains (#939)", () => {
41124132
pressure: 1013,
41134133
station: "north",
41144134
});
4135+
expect(value(first?.bindings ?? [], "ran")).toEqual({
4136+
exitCode: 0,
4137+
stdout: "ready",
4138+
stderr: "noted",
4139+
});
41154140

41164141
// Read back by the entry after it, each as the kind of value it was: an
41174142
// object stays an object, `<Json>`'s capture is the text it returned, and
41184143
// a Markdown component's text capture is what it rendered.
41194144
expect((yield* following(session, READS_CAPTURES)).ok).toBe(true);
4120-
expect(session.model.entries[1]?.terminal?.output).toContain("Read: 42/beta/42/true/2/1013");
4145+
expect(session.model.entries[1]?.terminal?.output).toContain(
4146+
"Read: 42/beta/42/true/2/1013/0:ready:noted",
4147+
);
41214148

41224149
// One publication per capture, and the component really ran once: these
41234150
// are values the run produced rather than a reconstruction of them.
@@ -4129,6 +4156,7 @@ describe("REPL entries: the root values a capture retains (#939)", () => {
41294156
"markdownText",
41304157
"markdownValue",
41314158
"paired",
4159+
"ran",
41324160
]);
41334161
// And no per-binding effect of any kind is in the history.
41344162
expect(recordedTypes(events)).not.toContain("root_binding");
@@ -4295,7 +4323,7 @@ const READS_SCOPES = [
42954323
describe("REPL entries: whose root a capture belongs to (#939)", () => {
42964324
beforeAll(() => useTempFileCompiler());
42974325

4298-
it("P3: a transparent region publishes, and every other scope keeps its own", function* () {
4326+
it("P3: whose root a capture is written in decides whether it crosses", function* () {
42994327
const { execution, session } = yield* capturing(SCOPES);
43004328
expect((yield* session.join()).ok).toBe(true);
43014329

@@ -4305,32 +4333,42 @@ describe("REPL entries: whose root a capture belongs to (#939)", () => {
43054333
expect(value(first?.bindings ?? [], "chosen")).toBe("under if");
43064334

43074335
const events = yield* execution.stream.readAll();
4308-
// Each local capture really ran, which is what makes their absence below an
4309-
// absence of publication rather than an absence of work: one `<Syntax>` read
4336+
// Each local capture really ran, which is what makes the absences below an
4337+
// absence of root data rather than an absence of work: one `<Syntax>` read
43104338
// per iteration, one per spawned branch, and one inside the fragment.
43114339
expect(recordedTypes(events).filter((type) => type === "syntax_symbols").length).toBe(5);
43124340
expect(recordedTypes(events)).toContain("generated_xmd");
43134341

43144342
// The component's own `<Let>`, the iteration's `let` and the ordinary
4315-
// captures written inside the iteration, the spawned branches and the
4316-
// admitted fragment are each somebody else's: the environment they were
4317-
// written in is not this root's, so none of them becomes a root value.
4318-
const locals = ["shapeLocal", "n", "inEach", "inSpawn", "alsoSpawn", "inFragment"];
4343+
// captures written inside the iteration and the spawned branches are each
4344+
// somebody else's: the environment they were written in is not this root's,
4345+
// so none of them becomes a root value.
4346+
const locals = ["shapeLocal", "n", "inEach", "inSpawn", "alsoSpawn"];
43194347
for (const local of locals) {
43204348
expect(names(first?.bindings ?? [])).not.toContain(local);
43214349
}
4322-
// `<Each as>` is the exception, and not an exception to the rule: the
4323-
// aggregate it names is written at the root, by the root, so it is this
4324-
// entry's own data even though the values it joined were iteration-local.
4350+
// `<Each as>` is not an exception to that rule: the aggregate it names is
4351+
// written at the root, by the root, so it is this entry's own data even
4352+
// though the values it joined were iteration-local.
43254353
expect(typeof value(first?.bindings ?? [], "joined")).toBe("string");
4326-
expect(settledNames(projected(events), 1).sort()).toEqual(["chosen", "joined", "shaped"]);
4354+
// Neither is the admitted fragment. A fragment expands against the
4355+
// document's own environment rather than one of its own — that is what it
4356+
// has always done — so a capture written in it is written in this root,
4357+
// and where its source came from does not make it somebody else's.
4358+
expect(typeof value(first?.bindings ?? [], "inFragment")).toBe("string");
4359+
expect(settledNames(projected(events), 1).sort()).toEqual([
4360+
"chosen",
4361+
"inFragment",
4362+
"joined",
4363+
"shaped",
4364+
]);
43274365
expect(recordedTypes(events)).not.toContain("root_binding");
43284366

43294367
expect((yield* following(session, READS_SCOPES)).ok).toBe(true);
43304368
// `props` is the entry's own namespace, which every entry validates for
43314369
// itself: inherited or not, it is an object here because this root has one.
43324370
expect(session.model.entries[1]?.terminal?.output).toContain(
4333-
"Read: under if/undefined/undefined/string/undefined/undefined/undefined/undefined/object",
4371+
"Read: under if/undefined/undefined/string/undefined/undefined/undefined/string/object",
43344372
);
43354373
});
43364374
});
@@ -4466,32 +4504,50 @@ describe("REPL entries: what a failure and an interruption leave published (#939
44664504
expect(partitioned(events).map((segment) => segment.settled)).toEqual([false]);
44674505
});
44684506

4469-
it("P5: a recorded cancelled close exposes its own facts only, and permits a successor", function* () {
4470-
const { execution, session } = yield* capturing(
4471-
['<Let as="kept" value="one" />', "", "One.", ""].join("\n"),
4472-
);
4473-
expect((yield* session.join()).ok).toBe(true);
4474-
const events = yield* execution.stream.readAll();
4475-
const [only] = partitioned(events);
4476-
// The close is doctored and only the close: the entry before it really ran
4477-
// and really captured. Cancelling a live entry appends no close at all, so
4478-
// this is the one way to stand where a cancelled entry has settled.
4479-
const holder = replExecution(withClose(events, only, cancelled("root")));
4507+
it("P5: a recorded cancellation keeps the facts before it and adds no map", function* () {
4508+
// The real unfinished prefix the row above leaves behind: an entry that
4509+
// reached a capture, recorded its own eval export, and stopped at a
4510+
// question it was never answered. Nothing about it is doctored.
4511+
const execution = replExecution();
4512+
yield* scoped(function* () {
4513+
const session = opened(yield* submitReplEntry({ execution, source: PUBLISHES_THEN_ASKS }));
4514+
yield* asking(session);
4515+
});
4516+
const prefix = yield* execution.stream.readAll();
4517+
expect(prefix.some((event) => event.type === "close")).toBe(false);
4518+
expect(names(projected(prefix).entries[0]?.bindings ?? [])).toEqual(["schema"]);
4519+
4520+
// Cancelling a live entry appends no close at all, so a file where a
4521+
// cancelled entry has settled is one where the cancellation was recorded
4522+
// for it afterwards. Built on a copy, so the prefix stays the prefix.
4523+
const holder = replExecution(cancelledAfter(prefix));
44804524

44814525
yield* scoped(function* () {
44824526
const reopened = opened(yield* openReplSession({ execution: holder }));
44834527
expect(reopened.model.entries[0]?.terminal?.status).toBe("cancelled");
4484-
// A cancellation is not a result, so it carries no computed data — and
4485-
// the successful one it replaced was discarded rather than kept. What the
4486-
// entry hands on is what this record actually holds, which is nothing.
4528+
// A cancellation is not a result, so it carries no computed data of its
4529+
// own: there is no map here, and none is invented for it.
44874530
expect(reopened.model.entries[0]?.terminal?.bindings).toBeUndefined();
4488-
expect(reopened.model.entries[0]?.bindings ?? []).toEqual([]);
4489-
// It still settles the entry, so a successor may follow it; the name the
4490-
// cancelled entry had captured simply resolves to nothing there.
4491-
accepted(yield* reopened.submit("Two: {kept}\n"));
4531+
// What it does not do is unretain what came before it. The eval export
4532+
// this entry really recorded is a fact the file holds, and cancelling the
4533+
// entry that made it does not take it back — while the capture the entry
4534+
// reached, which was never recorded anywhere, is still absent.
4535+
expect(names(reopened.model.entries[0]?.bindings ?? [])).toEqual(["schema"]);
4536+
4537+
// It settles the entry, so a successor may follow it, and the successor
4538+
// inherits exactly that: the recorded fact and not the unrecorded one.
4539+
accepted(yield* reopened.submit("Two: {schema.type}/{held}\n"));
44924540
yield* reopened.join();
4493-
expect(reopened.model.entries[1]?.terminal?.output).not.toContain("Two: one");
4541+
// The recorded export resolves; the unrecorded capture is not a name
4542+
// here at all, so its brace renders exactly as it was written.
4543+
expect(reopened.model.entries[1]?.terminal?.output).toContain("Two: object/{held}");
4544+
expect(reopened.model.entries[1]?.terminal?.output).not.toContain("acknowledged");
44944545
});
4546+
4547+
// And the unfinished prefix this was built from is untouched: its own
4548+
// reading still has no outcome, and it still permits no successor.
4549+
expect(yield* execution.stream.readAll()).toEqual(prefix);
4550+
expect(projected(prefix).entries[0]?.terminal).toBeUndefined();
44954551
});
44964552
});
44974553

@@ -4618,12 +4674,25 @@ function withSettledBindings(events: readonly DurableEvent[], carried: Json): Du
46184674
});
46194675
}
46204676

4621-
/** One entry that captures a live function and binds it again by reference. */
4677+
/**
4678+
* One entry that captures a live function and binds it again by reference.
4679+
*
4680+
* `transient` is the third name and the one nothing ever retains: it holds
4681+
* ordinary JSON for the length of a sentence and is then bound to the handle,
4682+
* through captures rather than an `eval` export — an export would retain the
4683+
* JSON and the row would be asking a different question.
4684+
*/
46224685
const CAPTURES_LIVE = [
46234686
'<Handle as="saved" />',
46244687
"",
46254688
'<Let as="localOnly" value={saved} />',
46264689
"",
4690+
'<Let as="transient" value={{ step: 1 }} />',
4691+
"",
4692+
"Transient here: {transient.step}",
4693+
"",
4694+
'<Handle as="transient" />',
4695+
"",
46274696
"```js eval",
46284697
"const used = `${saved()}/${localOnly === saved}`;",
46294698
"```",
@@ -4648,7 +4717,10 @@ describe("REPL entries: the values that stay in the entry that made them (#939)"
46484717
// by reference, in this entry, as the exact values the producer made.
46494718
expect((yield* following(session, CAPTURES_LIVE)).ok).toBe(true);
46504719
expect(session.model.entries[1]?.terminal?.output).toContain("Used: still live/true");
4651-
expect(counted.handle).toBe(1);
4720+
// The transient value really was ordinary JSON while it stood, which is
4721+
// what makes its absence below an absence of retention rather than of work.
4722+
expect(session.model.entries[1]?.terminal?.output).toContain("Transient here: 1");
4723+
expect(counted.handle).toBe(2);
46524724

46534725
// No record of its own for either name: the second entry's own outcome
46544726
// omits both, because neither value is JSON. What it does carry is the
@@ -4658,6 +4730,11 @@ describe("REPL entries: the values that stay in the entry that made them (#939)"
46584730
expect(recordedTypes(events)).not.toContain("root_binding");
46594731
expect(settledNames(projected(events), 1)).toEqual(["saved"]);
46604732
expect(settledNames(projected(events), 2)).toEqual(["used"]);
4733+
// `transient` among them: a value a name held and lost before the entry
4734+
// settled is not history. The result reads the root as it stands, and what
4735+
// stands under that name is a function — so there is nothing to carry, and
4736+
// no earlier value to go back for.
4737+
expect(settledNames(projected(events), 2)).not.toContain("transient");
46614738

46624739
// So the name keeps the last value anything durably retained under it,
46634740
// and a name only ever bound to a live value is absent from inheritance.
@@ -4666,6 +4743,7 @@ describe("REPL entries: the values that stay in the entry that made them (#939)"
46664743
const cold = projected(yield* execution.stream.readAll());
46674744
expect(entryInitialBindings(cold)["saved"]).toBe("alpha");
46684745
expect(Object.hasOwn(entryInitialBindings(cold), "localOnly")).toBe(false);
4746+
expect(Object.hasOwn(entryInitialBindings(cold), "transient")).toBe(false);
46694747
});
46704748
});
46714749

0 commit comments

Comments
 (0)