Skip to content

Commit ecb957f

Browse files
committed
📝 Record the composition and the lifecycle authority as shipped
Three merges landed under this target, and the inventory moves twice. #293 is complete. `<Repository>`, the self-closing `<Worktree>` and the lexical `<Dir>` are registered by `@executablemd/workflow/composition`, so the composition this document is written against executes under a workflow run. The unresolved set is seven names, not ten, and each still names the issue that owes it. What that leaves is a host distinction rather than a build one: registration is scope-local and the workflow host installs it, so plain `xmd run` resolves none of the three — evidence about which host ran a document, never about whether a component exists. The documents say that in as many words, because the alternative reads as a regression. #367's second slice is here too. The executor lock owns lifecycle transitions, so single-executor ownership, atomic begin and settle, cancellation and deletion are shipped. Cancellation does not signal a live executor: it refuses without mutation and tells the caller to interrupt the foreground process, and Ctrl-C tears the scope down in order and leaves the run resumable. Durable suspension and releasing the executor at a checkpoint stay open, which is still what keeps a checkpoint answering inside the execution that asked. The composition itself is untouched — the settled self-closing `<Worktree … as>` followed by lexical `<Dir path={worktree}>`, with no binding exception — and #301 still owns reachability for the five stage components.
1 parent 963238a commit ecb957f

6 files changed

Lines changed: 75 additions & 43 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -93,10 +93,10 @@ frontier, releases the executor, and reports the run ID and stop reason;
9393
process nor the Agent sessions need to stay alive in between. `xmd workflow
9494
start` and `xmd workflow resume` are shipped (#366), and a resume continues from
9595
the retained frontier; `xmd workflow status` reports a stopped run's retained
96-
status and stop reason without advancing it (#460). What is not built is the
97-
boundary itself — a checkpoint that releases the executor, and the
98-
single-executor ownership and atomic lifecycle transitions that decide who may
99-
continue a run, remain #367. `<Stage>` is not the answer: it was
96+
status and stop reason without advancing it (#460). The single-executor
97+
ownership and atomic lifecycle transitions that decide who may continue a run
98+
are shipped too, owned by the executor lock (#466). What is not built is the
99+
boundary itself — a checkpoint that releases the executor remains #367. `<Stage>` is not the answer: it was
100100
rejected as architecture, because the root document is the workflow and a durable
101101
run may continue through several document executions without inventing
102102
subdivisions between them (#298, closed).
@@ -183,9 +183,10 @@ Signal 3 has a shipped in-run form. `<Elicit>` asks a person a schema-validated
183183
question during execution and binds the validated answer, and `xmd run` composes
184184
the WebForm provider so that question opens a loopback browser form. Under
185185
`xmd workflow` the same question is to become a durable suspension that releases
186-
the executor and resumes later; the executor ownership that makes releasing one
187-
safe is #367 and is unbuilt, so today the question is answered inside the
188-
document execution that asked it, under whichever command started it.
186+
the executor and resumes later. The executor ownership that makes releasing one
187+
safe is shipped (#466); the release itself is not, so today the question is
188+
answered inside the document execution that asked it, under whichever command
189+
started it.
189190

190191
### Runtime intervention
191192

@@ -445,8 +446,9 @@ shipped:
445446
path, no write handle. It is used for source changes, explicit exports, or
446447
external tools that require a path, not as the default agent handoff.
447448

448-
The rest are not implemented, and they are explicit composition rather than one
449-
implicit workspace:
449+
The composition components are built and registered by the workflow host
450+
(#293, shipped); the durable Git and forge effects below them are not. Both are
451+
explicit composition rather than one implicit workspace:
450452

451453
- `<Repository>` authorizes a Git locator, resolves an optional base once, pins
452454
that commit, and creates the named primary checkout inside the run's Workspace.
@@ -465,9 +467,12 @@ implicit workspace:
465467
- `<Dir>` is lexical cwd and nothing else: it establishes a bound path as cwd for
466468
its children, renders them normally, and restores the enclosing cwd when it
467469
closes. Making a directory readable by an Agent is `<Agent.AddDir>` (#302), a
468-
separate operation on purpose, and cwd never implies it. `<Dir>` is unbuilt,
469-
and #293 owns the boundary this composition consumes unless an earlier issue
470-
supplies it first.
470+
separate operation on purpose, and cwd never implies it. All three —
471+
`<Repository>`, `<Worktree>` and `<Dir>` — are registered by
472+
`@executablemd/workflow/composition`, so they resolve under a workflow run and
473+
under no other host: plain `xmd run` composes no workflow and reports them
474+
unresolved, which says which host ran the document rather than whether the
475+
component exists.
471476
- `<Git.Switch>`, `<Git.Add>` and staged-only `<Git.Commit>` operate on the
472477
contextual checkout as Workspace-local durable effects (#294). `<Git.Push>` is
473478
explicit and separate (#370), and `<PullRequest>` requires that pushed head
@@ -596,7 +601,11 @@ reports is descriptive evidence about an event rather than identity.
596601

597602
The rest of the lifecycle is not built. Durable suspension and releasing the
598603
executor at a checkpoint, the single-executor ownership and atomic lifecycle
599-
transitions around them, and cancellation and deletion remain #367; versioned
604+
transitions around them, and cancellation and deletion are shipped as #367's
605+
second slice (#466): the executor lock owns every transition, and a cancellation
606+
that meets a live executor refuses without mutation and directs the caller to
607+
interrupt the foreground process rather than signalling it. Durable suspension
608+
and releasing the executor at a checkpoint remain #367; versioned
600609
history checkpoints, compatible forks, `history --forkable`, and forkability
601610
reasons remain #368.
602611

‎specs/markdown-agents-vision.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -195,10 +195,11 @@ deterministically and passes required content into agent prompts explicitly.
195195
`<File>` and `<Glob>` already perform such operations, and the command already
196196
supplies the run around them: `xmd workflow start` creates a workflow run with
197197
one retained Workspace and `xmd workflow resume` continues it from the retained
198-
journal (#366, shipped). What that run still lacks is the composition and the
199-
effects inside it — named `<Repository>` and `<Worktree>` (#293), deterministic
198+
journal (#366, shipped). The composition inside that run is there too: named
199+
`<Repository>`, `<Worktree>` and lexical `<Dir>` are registered by the workflow
200+
host (#293, shipped). What it still lacks are the durable effects — deterministic
200201
local Git effects (#294), explicit `<Git.Push>` (#370), `<PullRequest>` (#295),
201-
and `<Issue>` (#296). None of those is built. Together they cover the work that
202+
and `<Issue>` (#296) — none of which is built. Together they cover the work that
202203
should not depend on model judgment:
203204

204205
- retain each handoff, plan, review, and decision as a filtered journal event

‎workflows/adversarial-implementation/UserCheckpoint.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -214,9 +214,10 @@ is released, and `xmd workflow resume <run-id>` continues once the answer is
214214
available — the process, the Workspace attachment, and the agent processes need
215215
not stay alive in between. `start` and `resume` are shipped (#366) and a resume
216216
already restores this component's journaled answer rather than asking again;
217-
releasing the executor at the question, and the ownership that decides who may
218-
continue the run, are #367 and unbuilt. So today the question is answered inside
219-
the document execution that asked it, under either command.
217+
the ownership that decides who may continue the run is shipped (#466);
218+
releasing the executor at the question is #367 and unbuilt. So today the
219+
question is answered inside the document execution that asked it, under either
220+
command.
220221

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

‎workflows/adversarial-implementation/primitives.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -263,23 +263,27 @@ supplied material rather than a repository. `Implementation` has no such
263263
exemption: its loop body invokes `<Expand>`, `<Git.Add>`, `<Git.Commit>`,
264264
`<Git.Push>`, `<PullRequest>`, and `<Issue>`, which resolve to nothing.
265265

266-
Ten names in this workflow resolve to nothing today, and each is owed by one
266+
Seven names in this workflow resolve to nothing today, and each is owed by one
267267
issue:
268268

269269
| Name | Owed by |
270270
| --- | --- |
271271
| `<Agent.AddDir>` | #302 |
272-
| `<Dir>` | #293 |
273272
| `<Expand>` | #369 |
274273
| `<Git.Add>` | #294 |
275274
| `<Git.Commit>` | #294 |
276275
| `<Git.Push>` | #370 |
277276
| `<Issue>` | #296 |
278277
| `<PullRequest>` | #295 |
279-
| `<Repository>` | #293 |
280-
| `<Worktree>` | #293 |
281278

282-
`<Dir>` joined that list with the composition #293 settled. A generic component
279+
`<Repository>`, `<Worktree>` and `<Dir>` have left that list:
280+
`@executablemd/workflow/composition` registers all three (#293, shipped), which
281+
is what makes the composition below executable under a workflow run. Because
282+
registration is scope-local and the workflow host installs it, plain `xmd run`
283+
resolves none of them — evidence about the host a document ran under, never
284+
about whether a component is built.
285+
286+
The composition itself is unchanged, and it is why the two forms exist. A generic component
283287
invocation written with `as=` is an ordinary private capture — it binds its
284288
result and contributes nothing at the call site — and `<Repository>` and
285289
`<Worktree>` receive no exception to it. So a lexical
@@ -315,7 +319,8 @@ whose dependency order this workflow consumes in the same sequence.
315319
| commit a Workspace mutation, its logical root, and the journal result atomically | #365 | shipped |
316320
| foreground `xmd workflow start` / `resume` with an implicit Workspace and declarative `<File>` effects | #366 | shipped |
317321
| read-only `status`, `list` and `history` over immutable lifecycle snapshots | #367 slice 1, delivered by #460 | shipped |
318-
| durable suspension, releasing the executor at a checkpoint, single-executor ownership, atomic lifecycle transitions, cancellation, deletion | #367 | open |
322+
| single-executor ownership, atomic begin/settle, cancellation, deletion, all owned by the executor lock | #367 slice 2, delivered by #466 | shipped |
323+
| durable suspension, and releasing the executor at a checkpoint | #367 | open |
319324
| versioned history checkpoints, compatible forks, `history --forkable` and forkability reasons | #368 | open |
320325

321326
`xmd workflow start` is what makes this document a workflow rather than a script,
@@ -352,7 +357,7 @@ component search path is introduced for workflow execution. The mechanism is
352357

353358
| Capability | Issue | Status |
354359
| --- | --- | --- |
355-
| `<Repository>` and self-closing `<Worktree>` as named Workspace composition, and the lexical `<Dir>` boundary that consumes a bound checkout path | #293 | open |
360+
| `<Repository>`, self-closing `<Worktree>`, and the lexical `<Dir>` boundary that consumes a bound checkout path | #293 | shipped — registered by the workflow host |
356361
| `<Git.Switch>`, `<Git.Add>`, staged-only `<Git.Commit>` | #294 | open |
357362
| shared external forge-effect reconciliation | #297 | open |
358363
| explicit `<Git.Push>` | #370 | open |

‎workflows/adversarial-implementation/runtime.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -135,9 +135,18 @@ a completed run replays it in full. Reading a run back is shipped too —
135135
snapshots, taking no executor lease, advancing nothing, attaching no Workspace,
136136
and appending nothing (#367's first slice, delivered by #460).
137137

138-
Suspension is not. Releasing the executor at a checkpoint, the single-executor
139-
ownership that decides who may continue a run, atomic lifecycle transitions, and
140-
`cancel` and `delete` remain #367 and unbuilt; forks and forkability remain
138+
Lifecycle authority is here too. The executor lock owns the transitions, so
139+
single-executor ownership, atomic begin and settle, `cancel` and `delete` are
140+
shipped (#367's second slice, delivered by #466). Cancellation never reaches
141+
into a live document execution: when the lock reports a live workflow executor,
142+
`xmd workflow cancel` refuses without mutation and tells the caller to interrupt
143+
the foreground process, and Ctrl-C tears the scope down in order, publishes
144+
`interrupted` and leaves the run resumable. Without a live executor the
145+
management host acquires the lock and publishes `cancelled` inside the
146+
transaction that validates it.
147+
148+
What is still missing is the wait itself: durable suspension, and releasing the
149+
executor at a checkpoint, remain #367 and unbuilt; forks and forkability remain
141150
#368.
142151

143152
## Cleanup follows the invocation

‎workflows/adversarial-implementation/start.md‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -428,14 +428,18 @@ checkpoint in an `<Answers>` region instead of reaching a person.
428428
`Planning` each name `<Agent.AddDir>`, which does not exist, so their bodies run
429429
only once that registration is supplied or removed.
430430

431-
**Not expressible.** Every component that composes the Workspace or performs a
432-
durable environmental effect. These ten names resolve to nothing today:
431+
**Composed by the workflow host.** `<Repository>`, `<Worktree>` and `<Dir>` are
432+
built and registered by `@executablemd/workflow/composition` (#293, shipped),
433+
which is what makes the composition above executable under a workflow run.
434+
Registration is scope-local and the workflow host is what installs it, so plain
435+
`xmd run` — which composes no workflow — reports all three unresolved. That is
436+
where a document ran, not whether a component exists.
437+
438+
**Not expressible.** Every component that performs a durable environmental
439+
effect. These seven names resolve to nothing under either host:
433440

434441
| Written above | Supplied by | Status |
435442
| --- | --- | --- |
436-
| `<Repository>` | #293 | unbuilt |
437-
| `<Worktree>` | #293 | unbuilt |
438-
| `<Dir>` | #293 | unbuilt — the lexical cwd boundary this composition consumes, unless an earlier issue supplies it first |
439443
| `<Agent.AddDir>` and the read-only Agent ceiling | #302 | unbuilt |
440444
| `<Expand>` for Agent-generated XMD | #369 | unbuilt; public name open |
441445
| `<Git.Add>` | #294 | unbuilt |
@@ -444,9 +448,8 @@ durable environmental effect. These ten names resolve to nothing today:
444448
| `<PullRequest>` | #295 | unbuilt |
445449
| `<Issue>` | #296 | unbuilt |
446450

447-
So the complete flow is non-executable at two levels: the named checkouts the
448-
Workspace is composed from, and the implementation stage's durable Git and forge
449-
effects. What can be exercised today is discovery through plan convergence and
451+
So what remains non-executable is the implementation stage's durable Git and
452+
forge effects; the named checkouts the Workspace is composed from are here. What can be exercised today is discovery through plan convergence and
450453
the user gates around them, running in one document execution and one existing
451454
working directory, with commits, pushes, pull requests, and issues performed as
452455
explicit user-run steps between manual stages. Proving that shipped subset is
@@ -465,15 +468,19 @@ WorkflowRuns and filtered journals are stored and looked up by public run ID
465468
Workspace mutation, its logical root, and its journal result publish in a single
466469
transaction ([#365](https://github.com/taras/executable.md/issues/365), shipped).
467470

468-
Two things still keep *this* document from being started that way, and neither
469-
is durability. The run's Workspace holds no repository until `<Repository>`,
470-
`<Worktree>`, and the `<Dir>` boundary that consumes the bound checkout path
471-
exist (#293), so the `<Glob>` above would search an empty filesystem. And a run pins its definition to one committed Git object and passes
472-
no repository component search path, so the stages beside it —
471+
The composition above is no longer what keeps *this* document from being started
472+
that way: `<Repository>`, the self-closing `<Worktree>` and the lexical `<Dir>`
473+
are registered by the workflow host (#293, shipped), so the run's Workspace does
474+
get its checkout and the `<Glob>` above has a filesystem to search.
475+
476+
What remains is reachability. A run pins its definition to one committed Git
477+
object and passes no repository component search path, so the stages beside it —
473478
`InstructionFiles`, `Discovery`, `UserCheckpoint`, `Planning`, `Implementation` —
474479
resolve to nothing under `xmd workflow start` and `xmd workflow resume`. Under
475480
`xmd run` they resolve as ordinary repository components on its search path,
476-
which is where the shipped subset is exercised.
481+
which is where the shipped subset is exercised — and where `<Repository>`,
482+
`<Worktree>` and `<Dir>` do *not* resolve, because plain `xmd run` composes no
483+
workflow.
477484

478485
Making `InstructionFiles`, `Discovery`, `UserCheckpoint`, `Planning`, and
479486
`Implementation` reachable under `xmd workflow start` and `xmd workflow resume`

0 commit comments

Comments
 (0)