Skip to content

Commit 5f6f961

Browse files
committed
📝 Separate the shipped suspension substrate from what this Markdown calls
The documents had swung from one error to its opposite. They once said durable suspension was unbuilt; the last commit corrected that and overshot, saying an `<Elicit>` under `xmd workflow` *becomes* a durable suspension and that these checkpoints release the executor. Neither is true, and the two mistakes are the same mistake: reading shipped substrate as a shipped integration. What is shipped is `suspendFor()` — a run waits, gives its executor lock back, and a typed answer can be delivered to it (#367, #300). It is an Api operation. There is no v1 Markdown element that spells it, a suspension is a different mechanism from `<Elicit>`, which asks inside the execution already running, and this workflow installs no component or middleware that turns one into the other. So no checkpoint here releases the executor, delivery executes nothing, and nothing schedules a resume. Consuming that substrate is #301's supervised composition, and the documents now say exactly that without inventing a spelling or a bridge for it. Two smaller corrections fall out of the same pass. `<Git.Add>` and `<Git.Commit>` were still listed among names that resolve to nothing, when they are two of the six registrations the workflow host supplies alongside `<Repository>`, `<Worktree>`, `<Dir>` and `<Git.Switch>`. And the forge read that hands a network-denied reviewer a pull request's reviews, comments and checks is no longer unowned: `<Fetch>` reads over HTTP and retains what it read (#456). No stage writes those fetches yet, and admitting `<Fetch>` inside generated XMD stays #369's. The component probe now asserts four exact categories rather than a set — 16 ordinary, 5 bundled stages, 5 issue-owned unresolved, 6 workflow-host-only — and fails if any component the documents write goes unclassified or lands in the wrong group.
1 parent a483a5e commit 5f6f961

7 files changed

Lines changed: 114 additions & 78 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 46 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,12 @@ what makes exhaustion a distinct outcome without a separate label, which is what
6565
#290 settled: an exhausted loop is neither convergence nor ordinary successful
6666
completion, it starts no implementation and no later durable effect, and it asks
6767
the user for direction rather than answering on the stage's own account. A
68-
composed workflow turns that request into a durable suspension, which is shipped
69-
(#367): the run waits, gives its executor lock back, and continues when a typed
70-
answer is delivered and someone resumes it. Nothing schedules that resumption,
71-
and resume never reads exhaustion, silence, or an unchanged verdict as
72-
approval.
68+
a composed workflow is meant to turn that request into a durable suspension. The
69+
substrate for one is shipped — `suspendFor()` waits, gives the executor lock
70+
back, and a typed answer can be delivered to the waiting run (#367, #300) — but
71+
it is an Api operation, not something this Markdown calls: nothing here converts
72+
a checkpoint into a suspension. So exhaustion asks in the report today, and
73+
resume never reads exhaustion, silence, or an unchanged verdict as approval.
7374

7475
`proceed: true` authorizes the exact transition and effects the checkpoint
7576
assessed, and nothing more. The rule binds the material as much as the decision:
@@ -88,17 +89,25 @@ after the checkpoint.
8889
A checkpoint that found no material choice produces an explicit `proceed: true`
8990
recording why, so a transition never advances because a decision was missing.
9091

91-
Stopping *at* the boundary is a durable suspension rather than a construct. A
92-
checkpoint that reaches a person records its pending request and the Workspace
93-
frontier, releases the executor, and reports the run ID and stop reason;
94-
`xmd workflow resume` continues there once the answer is available. Neither the
95-
process nor the Agent sessions need to stay alive in between. `xmd workflow
96-
start` and `xmd workflow resume` are shipped (#366), and a resume continues from
97-
the retained frontier; `xmd workflow status` reports a stopped run's retained
98-
status and stop reason without advancing it (#460). The single-executor
99-
ownership and atomic lifecycle transitions that decide who may continue a run
100-
are shipped too, owned by the executor lock (#466). What is not built is the
101-
boundary itself — a checkpoint that releases the executor remains #367. `<Stage>` is not the answer: it was
92+
Stopping *at* the boundary is a durable suspension rather than a construct: a
93+
checkpoint that reaches a person should record its pending request and the
94+
Workspace frontier, give the executor lock back, and report the run ID and stop
95+
reason, so that neither the process nor the Agent sessions need to stay alive
96+
until `xmd workflow resume` continues there.
97+
98+
Every piece of that is shipped. `start` and `resume` (#366); `status` reporting
99+
a stopped run's retained status and stop reason without advancing it (#460); the
100+
single-executor ownership and atomic transitions owned by the executor lock
101+
(#466); `suspendFor()`, which suspends a run durably and releases its lock
102+
(#367); and typed delivery of an answer to a waiting run (#300).
103+
104+
What is missing is the join, not the parts. `suspendFor()` is an Api operation a
105+
host or component calls — there is no v1 Markdown element that spells it, and a
106+
suspension is a different thing from `<Elicit>`, which asks a question inside the
107+
execution that is already running. This workflow contains no component or
108+
middleware that turns its `<Elicit>` calls into `suspendFor()`, so its
109+
checkpoints do not release the executor today. Consuming that substrate belongs
110+
to #301's supervised composition. `<Stage>` is not the answer: it was
102111
rejected as architecture, because the root document is the workflow and a durable
103112
run may continue through several document executions without inventing
104113
subdivisions between them (#298, closed).
@@ -183,12 +192,15 @@ would have been used without detecting or prioritizing them.
183192
Signal 3 has a shipped in-run form. `<Elicit>` asks a person a schema-validated
184193
question during execution and binds the validated answer, and `xmd run` composes
185194
the WebForm provider so that question opens a loopback browser form. Under
186-
`xmd workflow` the same question becomes a durable suspension that releases the
187-
executor and resumes later. Both halves are shipped — the ownership that makes
188-
releasing one safe (#466) and the wait that gives the lock back (#367) — and a
189-
typed answer can be delivered to a suspended run (#300). Delivery does not
190-
execute anything: it records the answer, and a resume is still an explicit act
191-
that someone performs. Nothing schedules it.
195+
`xmd workflow` that same question is still `<Elicit>`, answered inside the
196+
execution that asked it. A durable suspension is a different mechanism, and its
197+
substrate is shipped: `suspendFor()` waits and gives the executor lock back
198+
(#367), the lock's ownership decides who may continue (#466), and a typed answer
199+
can be delivered to a waiting run (#300). None of that is reached from Markdown
200+
here — `suspendFor()` is an Api operation with no v1 element spelling it, and
201+
this workflow installs nothing that converts an `<Elicit>` into one. Delivery
202+
also executes nothing: it records the answer, and resuming stays an explicit act
203+
nobody schedules.
192204

193205
### Runtime intervention
194206

@@ -278,11 +290,14 @@ review.
278290
identity, number, URL, state, head SHA and base SHA (#295). Existing reviews,
279291
comments and check results are separate reads rather than fields on a creation
280292
result that would otherwise claim to stay fresh against a remote that keeps
281-
changing. **That read is not defined by any open issue.** The requirement it must
282-
satisfy is unchanged: the reviewer receives every existing review with its body,
283-
every comment, and every check result, iterated rather than stringified — a
284-
review that cannot see a failing check or an existing objection is not
285-
adversarial, it is uninformed.
293+
changing. **That read is `<Fetch>`'s** (#456, shipped): a document reads over
294+
HTTP and retains what it read, so a network-denied reviewer can be handed a pull
295+
request's current state without the Agent ever reaching the network. The
296+
requirement it must satisfy is unchanged: the reviewer receives every existing
297+
review with its body, every comment, and every check result, iterated rather
298+
than stringified — a review that cannot see a failing check or an existing
299+
objection is not adversarial, it is uninformed. No stage writes those fetches
300+
yet, and admitting `<Fetch>` inside generated XMD remains #369's.
286301

287302
The user's checkpoint carries the same evidence. An existing objection reaches
288303
the person approving the change in its own words, not only as the planner
@@ -951,9 +966,10 @@ The exercise must resolve enough of these to implement one vertical slice:
951966
rather than a second one — expansion identity alone cannot answer it, so the
952967
effect's natural key has to, and a head that deliberately advanced on the same
953968
branch must be distinguishable from a conflicting one (#295, #297)?
954-
5. Which forge read returns a pull request's existing reviews, comments, and
955-
check results to a network-denied reviewer? `<PullRequest>`'s creation result
956-
is deliberately minimal, and no open issue owns that read.
969+
5. Which fetches does a review actually write? `<PullRequest>`'s creation result
970+
is deliberately minimal, and `<Fetch>` (#456) is how a network-denied reviewer
971+
is handed the rest — but no stage composes those reads yet, and admitting
972+
`<Fetch>` inside generated XMD stays #369's.
957973
6. Which host mechanism closes the validate-then-use race for each supported
958974
runtime, now that a run-owned Workspace resolves a document path without
959975
producing a host path at all (#227)?

‎workflows/adversarial-implementation/Implementation.md‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -477,20 +477,23 @@ identity, number, URL, state, head SHA and base SHA. Reviews, comments and check
477477
results are *not* fields on it, because a creation result that pretended to stay
478478
fresh would be lying about a remote that keeps changing. They are separate reads.
479479

480-
**Missing: that read.** No component or issue defines the forge observation that
481-
returns existing reviews, comments and check results for a pull request. The
482-
requirement is unchanged and worth stating exactly, because it is what makes the
483-
review adversarial rather than uninformed:
480+
**That read has a component now.** `<Fetch>` reads over HTTP from Markdown and
481+
retains what it read (#456, shipped), which is what a network-denied reviewer
482+
needs: the document fetches a pull request's existing reviews, comments and
483+
check results and renders them into the prompt, while the Agent itself stays
484+
denied the network. The requirement is unchanged and still worth stating
485+
exactly, because it is what makes the review adversarial rather than uninformed:
484486

485487
- the reviewer must receive every existing review with its body, every comment,
486488
and every check result, iterated rather than stringified; and
487489
- the user's checkpoint must carry the same consequential content, so a person
488490
approving the change reads the original objections in their own words rather
489491
than the planner's summary of them.
490492

491-
Until that read exists, this stage reviews the change it just made against the
492-
plan and the checkout, and an objection raised by anyone other than the planner
493-
does not reach either surface.
493+
This stage does not write those fetches yet, so today it reviews the change it
494+
just made against the plan and the checkout, and an objection raised by anyone
495+
other than the planner reaches neither surface. Admitting `<Fetch>` inside
496+
Agent-generated XMD is a separate question and stays #369's.
494497

495498
The verdict names one head. The prompt reviews the change at `headSha` against
496499
`baseSha`, and a moved head requires a fresh review — the same rule #295 states
@@ -582,7 +585,7 @@ revision turn, or acceptance.
582585
| `<Issue>` | #296 | unbuilt |
583586
| `<Git.Add>`, staged-only `<Git.Commit>` | #294 | shipped |
584587
| shared Git-host reconciliation behind push, pull request and issue | #297 | shipped — the surface, not the components over it |
585-
| the forge read that returns reviews, comments and checks | — | unowned |
588+
| the forge read that returns reviews, comments and checks | `<Fetch>` (#456) | shipped — this stage does not write it yet |
586589

587590
The agent, parsing, capture, and control-flow syntax runs today, and so do the
588591
local Git effects: `<Git.Add>` and `<Git.Commit>` are built. The loop body above

‎workflows/adversarial-implementation/Planning.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -301,14 +301,16 @@ later durable effect, and cannot be reported as convergence or success.
301301
What the caller does with it is ask the user. An exhausted planning loop returns
302302
to its caller for direction rather than terminating on its own account: five
303303
rounds of evidence did not converge, and only the user decides what happens
304-
next. Under a composed workflow that request becomes a durable suspension — the
305-
run records why it stopped and the material the user needs, releases its
306-
executor, and resumes only from explicit user direction, so neither exhaustion
307-
nor silence nor an unchanged verdict is ever read as approval. That lifecycle is
308-
shipped (#367): the run waits, gives its executor lock back, and continues when a
309-
typed answer is delivered and someone resumes it. Nothing schedules that, which
310-
is why this document still owns the boundary — and the boundary holds either
311-
way.
304+
next. Under a composed workflow that request is meant to become a durable
305+
suspension — the run recording why it stopped and the material the user needs,
306+
giving its executor lock back, and resuming only from explicit user direction.
307+
308+
The substrate exists: `suspendFor()` suspends and releases the lock (#367), and
309+
a typed answer can be delivered to the waiting run (#300). It is an Api
310+
operation with no v1 Markdown element, and this stage calls nothing that
311+
suspends, so today the request is reported rather than waited on. Either way
312+
neither exhaustion nor silence nor an unchanged verdict is read as approval, and
313+
the boundary this document owns holds.
312314

313315
Every `plan`, `verdict`, and `planCheckpoint` is already durable: each `<Prompt>`
314316
is one durable operation, each `<Elicit>` answer is journaled against its

‎workflows/adversarial-implementation/UserCheckpoint.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -208,18 +208,20 @@ that already knows the answer — a test, a demo, a non-interactive region — w
208208
this component in an `<Answers>` region and supplies it with `<Answer>` matchers,
209209
which changes who answers without changing this file.
210210

211-
Under `xmd workflow` the same question becomes a durable wait: the elicitation
212-
records its pending request and the Workspace frontier, the executor lock is
213-
given back, and `xmd workflow resume <run-id>` continues once the answer is
214-
available — the process, the Workspace attachment, and the agent processes need
215-
not stay alive in between. All of that is shipped: `start` and `resume` (#366),
216-
the ownership that decides who may continue a run (#466), the wait that releases
217-
the lock (#367), and typed delivery of an answer to a suspended run (#300). A
218-
resume restores this component's journaled answer rather than asking again.
219-
220-
What is not shipped is anything that acts on a delivered answer: delivery
221-
executes nothing and no scheduler resumes a run, so continuing one stays an
222-
explicit act.
211+
Under `xmd workflow` this stays an `<Elicit>`, answered inside the execution that
212+
asked it. A resume restores its journaled answer rather than asking again
213+
(#366).
214+
215+
The durable wait this checkpoint is eventually meant to become is a different
216+
mechanism, and its substrate is shipped: `suspendFor()` records a pending
217+
request, gives the executor lock back, and lets `xmd workflow resume <run-id>`
218+
continue once an answer is available (#367), with the ownership that decides who
219+
may continue (#466) and typed delivery of that answer (#300) alongside it.
220+
221+
This component does not call it. `suspendFor()` is an Api operation with no v1
222+
Markdown element, and nothing here converts an `<Elicit>` into one — so no
223+
checkpoint releases the executor today, delivery executes nothing, and nothing
224+
schedules a resume. Consuming that substrate is #301's supervised composition.
223225

224226
`<SafeParse>` exposes validation failures as data so the document can show the
225227
repair turn explicitly. It absorbs JSON syntax and schema-validation failures

‎workflows/adversarial-implementation/primitives.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -260,8 +260,9 @@ The document-level logic in `InstructionFiles`, `Discovery`, `Planning`, and
260260
`<Agent.AddDir>` registration `Discovery` and `Planning` need to give their
261261
agents the checkout. `UserCheckpoint` registers nothing, because it assesses
262262
supplied material rather than a repository. `Implementation` has no such
263-
exemption: its loop body invokes `<Expand>`, `<Git.Add>`, `<Git.Commit>`,
264-
`<Git.Push>`, `<PullRequest>`, and `<Issue>`, which resolve to nothing.
263+
exemption: its loop body invokes `<Expand>`, `<Git.Push>`, `<PullRequest>`, and
264+
`<Issue>`, which resolve to nothing. The `<Git.Add>` and `<Git.Commit>` beside
265+
them do resolve — under a workflow run, where the host registers them.
265266

266267
Five names in this workflow resolve to nothing today, and each is owed by one
267268
issue:

‎workflows/adversarial-implementation/runtime.md‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -113,10 +113,12 @@ must render everything the reviewer has to judge rather than pointing at it.
113113

114114
Three outcomes are distinct, and none of them is a failure of the document:
115115

116-
- **Suspension.** A checkpoint that reaches a person records its pending
117-
request and the Workspace frontier, releases the executor, and returns with a
118-
run ID and stop reason on standard error. `resume` continues when the answer
119-
is available.
116+
- **Suspension.** A run that calls `suspendFor()` records its pending request
117+
and the Workspace frontier, gives the executor lock back, and returns with a
118+
run ID and stop reason on standard error; `resume` continues when the answer
119+
is available (#367, shipped). It is an Api operation rather than a v1 Markdown
120+
element, and this workflow calls nothing that suspends, so no checkpoint here
121+
reaches it.
120122
- **Interruption.** Losing the executor outside an authored wait, including
121123
Ctrl-C, leaves the run `interrupted` and resumable at the journal frontier.
122124
- **Cancellation.** `xmd workflow cancel <run-id>` never reaches into a live
@@ -151,10 +153,12 @@ the foreground process, and Ctrl-C tears the scope down in order, publishes
151153
management host acquires the lock and publishes `cancelled` inside the
152154
transaction that validates it.
153155

154-
The wait is here too. A run suspends durably at an authored wait and gives its
155-
executor lock back (#367), and a typed answer can be delivered to it (#300).
156-
What is still missing is anything that *acts* on that: delivery executes
157-
nothing, no scheduler resumes a run, and forks and forkability remain #368.
156+
The wait is here too, as substrate. `suspendFor()` suspends a run durably and
157+
gives its executor lock back (#367), and a typed answer can be delivered to it
158+
(#300). What is missing is anything that reaches or acts on it: `suspendFor()`
159+
is an Api operation with no v1 element spelling it, this document calls nothing
160+
that suspends, delivery executes nothing, no scheduler resumes a run, and forks
161+
and forkability remain #368.
158162

159163
## Cleanup follows the invocation
160164

@@ -179,12 +183,18 @@ An automated iteration stops on the first applicable signal:
179183

180184
Signal 3 has a shipped in-run form: `<Elicit>` asks a person a schema-validated
181185
question during execution, and under `xmd run` the WebForm provider answers it
182-
in a browser. Under `xmd workflow` the same question becomes a durable
183-
suspension (#367, shipped), and a typed answer can be delivered to the run that
184-
is waiting ([#300](https://github.com/taras/executable.md/issues/300), shipped).
185-
Delivery is non-executing and arbitration between signals is not implemented:
186-
nothing schedules a resumption, and premature watcher semantics are deliberately
187-
excluded.
186+
in a browser. Under `xmd workflow` it is the same `<Elicit>`, answered inside the
187+
execution that asked it.
188+
189+
A durable suspension is a different mechanism, and it is shipped as substrate:
190+
`suspendFor()` suspends a run and gives its executor lock back (#367), and a
191+
typed answer can be delivered to the waiting run
192+
([#300](https://github.com/taras/executable.md/issues/300)). `suspendFor()` is an
193+
Api operation — there is no v1 Markdown element for it — and this workflow
194+
installs no component or middleware that turns an `<Elicit>` into one, so no
195+
checkpoint here releases the executor. Delivery executes nothing, arbitration
196+
between signals is not implemented, nothing schedules a resumption, and
197+
premature watcher semantics are deliberately excluded.
188198

189199
`<Loop>` already records part of this: it journals every iteration it enters and
190200
one terminal record whose outcome is `break`, `exhausted`, or `error`, and it

‎workflows/adversarial-implementation/start.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -299,10 +299,12 @@ passes the gate, so neither starts implementation or any later durable effect.
299299
Those two are reported differently, because they are different requests. A
300300
decline is finished: the user said no. Exhaustion is not — it is the workflow
301301
asking the user what to do after five rounds failed to converge (#290, settled).
302-
Under a composed workflow that request is where the run suspends durably for
303-
user direction (#367, shipped) and gives its executor lock back; here it is
304-
where the report asks. Neither exhaustion nor an unchanged verdict is ever read
305-
as approval, and nothing resumes the run on its own.
302+
Under a composed workflow that request is where the run should suspend durably
303+
for user direction. The substrate is shipped — `suspendFor()` waits and gives
304+
the executor lock back (#367), and a typed answer can be delivered (#300) — but
305+
it is an Api operation this document does not call, so here the report asks
306+
instead. Neither exhaustion nor an unchanged verdict is ever read as approval,
307+
and nothing resumes the run on its own.
306308

307309
A checkpoint that found no material choice still produces an explicit
308310
`proceed: true` with its reason, so nothing advances because a decision was

0 commit comments

Comments
 (0)