Skip to content

Commit d35cda8

Browse files
committed
📦 Close this workflow over the components its root declares
`start.md` now declares its five authored stages in its own frontmatter, and that is the whole integration — a declaration, not a mechanism. #493 does the rest: `xmd workflow start` and `resume` resolve exactly those names from the blobs the pinned definition commit holds, each normalized to a canonical repository-relative path and the blob's own object ID, and those entries join workflow-definition identity and retained-history admission. Change what a stage says and it is a different definition; a resume reconstructs the component from its retained source, a same-named file beside the definition answers nothing, and an undeclared name resolves to nothing at all. Workflow execution still searches no repository directories, and ordinary `xmd run` is untouched. That closes #301's component-bundle slice and nothing more. Reaching the stage names is not running the workflow: scheduling the loop and continuing it unattended are still owed, and this branch adds no scheduler, no automatic resume, no Agent ceiling, no generated-XMD admission, and no push, pull request or issue. The inventory shrinks to five as a result of what else has landed. `<Git.Switch>`, `<Git.Add>` and staged-only `<Git.Commit>` are built (#294), and the shared Git-host reconciliation the remote effects are built over is too (#297) — the surface, not the components over it. What still resolves to nothing is what reaches a remote or a forge, plus the Agent ceiling and the constrained evaluator: `<Agent.AddDir>`, `<Expand>`, `<Git.Push>`, `<PullRequest>`, `<Issue>`. Durable suspension and giving the executor lock back are shipped, and a typed answer can be delivered to a run that is waiting — but delivery executes nothing and no scheduler resumes anything, so the documents say the wait is real and the continuation is still someone's explicit act.
1 parent db43b64 commit d35cda8

7 files changed

Lines changed: 139 additions & 107 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,9 @@ 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 (#367, unbuilt),
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,
6971
and resume never reads exhaustion, silence, or an unchanged verdict as
7072
approval.
7173

@@ -142,25 +144,24 @@ from a second spelling of `<File>` or `<Git.Commit>`.
142144

143145
What that root Workspace supplies today is the document's filesystem, and only
144146
that. A run's `<File>` and `<Glob>` operations resolve inside the run's own
145-
transactional filesystem, which starts empty: the repository, worktree, process,
146-
and Agent capabilities the stages use are the composition #293 and #302 still
147-
owe it. The definition is pinned to one committed Git object and a run passes no
148-
repository component search path, so a repository component beside the
149-
definition — every stage below — resolves to nothing under `xmd workflow start`
150-
and `xmd workflow resume`.
151-
152-
Making them reachable is #301's. It owns the boundary between a run's retained
153-
workflow-definition identity and the component code that definition invokes:
154-
`InstructionFiles`, `Discovery`, `UserCheckpoint`, `Planning`, and
155-
`Implementation` are to become reachable under `start` and `resume` from code the
156-
trusted host authorized, with that code accounted for by workflow-definition
157-
identity and retained-history admission, so a resume or a replay cannot
158-
substitute current checkout content for retained component code and neither a
159-
document, public middleware, nor a checkout beside the retained root can widen
160-
what may execute. Ordinary `xmd run` resolution is unchanged, and workflow
161-
execution gains no generic repository component search path. What is stated here
162-
is the required authority and identity outcome; the mechanism is #301's to
163-
design and is subject to architecture review there.
147+
transactional filesystem: the repository, worktree and lexical working directory
148+
are composed by the workflow host (#293, shipped), while the Agent capabilities
149+
the stages use are still #302's. The definition is pinned to one committed Git
150+
object and a run passes no generic repository component search path — a root
151+
reaches its stages by declaring them instead.
152+
153+
That declaration is a **component bundle**, and it is shipped (#493, delivering
154+
#301's component-bundle slice). A root names its authored stages in its own
155+
frontmatter; `start` and `resume` resolve exactly those names from the blobs the
156+
pinned commit holds. Each normalizes to a canonical repository-relative path and
157+
the blob's own object ID, and those entries participate in workflow-definition
158+
identity and retained-history admission — so a resume or a replay reconstructs
159+
the component from its retained source, a mutable checkout beside the definition
160+
substitutes nothing, and an undeclared name resolves to nothing at all. Ordinary
161+
`xmd run` resolution is unchanged.
162+
163+
What #301 still owes is the supervised composition: scheduling the loop and
164+
continuing it unattended. Reaching the stage names is not running the workflow.
164165

165166
The stages that run today therefore run under `xmd run`, in one document
166167
execution and one existing working directory, with the user inspecting each
@@ -182,11 +183,12 @@ would have been used without detecting or prioritizing them.
182183
Signal 3 has a shipped in-run form. `<Elicit>` asks a person a schema-validated
183184
question during execution and binds the validated answer, and `xmd run` composes
184185
the WebForm provider so that question opens a loopback browser form. Under
185-
`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 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.
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.
190192

191193
### Runtime intervention
192194

@@ -825,11 +827,10 @@ checkout unless the user explicitly exports them.
825827
The exercise runs under `xmd run`, in one document execution and one existing
826828
working directory. The document logic — instruction discovery, the planner
827829
interview, plan convergence, the bounded repair turns, and the user gate — is
828-
executable on shipped syntax today. What a workflow run cannot yet give it is a
829-
checkout to work in and a way to reach these stages at all: the run's Workspace
830-
holds no repository until #293, and a pinned definition resolves no repository
831-
component beside it until #301 supplies authorized component code the retained
832-
definition's identity and admission account for.
830+
executable on shipped syntax today, and a workflow run can now give it both a
831+
checkout (#293) and its stage names, which the root declares as a component
832+
bundle resolved from the pinned commit (#493). What it cannot yet give is the
833+
supervision: scheduling the loop and continuing it unattended remain #301's.
833834

834835
The exercise succeeds when:
835836

‎workflows/adversarial-implementation/Implementation.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -534,7 +534,7 @@ exhaustion looks like: the user kept approving and the verdict never passed. The
534534
caller's gate rejects that pair, so an exhausted review cannot reach acceptance
535535
and starts no later durable effect. As in `Planning`, exhaustion is a request
536536
for user direction rather than a terminal answer of the stage's own (#290,
537-
settled); a composed workflow suspends there for it (#367, unbuilt).
537+
settled); a composed workflow suspends there for it (#367, shipped).
538538

539539
## Approval precedes durable effects
540540

@@ -577,16 +577,19 @@ revision turn, or acceptance.
577577
| --- | --- | --- |
578578
| `<Agent.AddDir>` and the read-only ceiling | #302 | unbuilt |
579579
| `<Expand>` | #369 | unbuilt; public name open |
580-
| `<Git.Add>`, `<Git.Commit>` | #294 | unbuilt |
581580
| `<Git.Push>` | #370 | unbuilt |
582581
| `<PullRequest>` | #295 | unbuilt |
583582
| `<Issue>` | #296 | unbuilt |
584-
| shared forge reconciliation behind push, pull request and issue | #297 | unbuilt |
583+
| `<Git.Add>`, staged-only `<Git.Commit>` | #294 | shipped |
584+
| shared Git-host reconciliation behind push, pull request and issue | #297 | shipped — the surface, not the components over it |
585585
| the forge read that returns reviews, comments and checks | — | unowned |
586586

587-
The agent, parsing, capture, and control-flow syntax runs today; the loop body
588-
above does not expand, because those names resolve to nothing. Until they land,
589-
the effects they stand for remain explicit user-run steps between manual stages.
587+
The agent, parsing, capture, and control-flow syntax runs today, and so do the
588+
local Git effects: `<Git.Add>` and `<Git.Commit>` are built. The loop body above
589+
still does not expand, because five names in it resolve to nothing — the Agent
590+
ceiling, the constrained evaluator, and the three components that reach a remote
591+
or a forge. Until those land, the effects they stand for remain explicit
592+
user-run steps between manual stages.
590593

591594
Props are namespaced throughout (#305). `proposal`, `commit`, `pullRequest`,
592595
`verdict`, `checkpointMaterial`, and `reviewCheckpoint` are authored bindings and

‎workflows/adversarial-implementation/Planning.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -305,8 +305,10 @@ next. Under a composed workflow that request becomes a durable suspension — th
305305
run records why it stopped and the material the user needs, releases its
306306
executor, and resumes only from explicit user direction, so neither exhaustion
307307
nor silence nor an unchanged verdict is ever read as approval. That lifecycle is
308-
#367's and is unbuilt; what this document owns is the boundary, and the boundary
309-
holds without it.
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.
310312

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

‎workflows/adversarial-implementation/UserCheckpoint.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -208,16 +208,18 @@ 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 is to become a durable wait: the
212-
elicitation records its pending request and the Workspace frontier, the executor
213-
is released, and `xmd workflow resume <run-id>` continues once the answer is
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
214214
available — the process, the Workspace attachment, and the agent processes need
215-
not stay alive in between. `start` and `resume` are shipped (#366) and a resume
216-
already restores this component's journaled answer rather than asking again;
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.
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.
221223

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

‎workflows/adversarial-implementation/primitives.md‎

Lines changed: 30 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -263,19 +263,23 @@ 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-
Seven names in this workflow resolve to nothing today, and each is owed by one
266+
Five 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 |
272272
| `<Expand>` | #369 |
273-
| `<Git.Add>` | #294 |
274-
| `<Git.Commit>` | #294 |
275273
| `<Git.Push>` | #370 |
276274
| `<Issue>` | #296 |
277275
| `<PullRequest>` | #295 |
278276

277+
`<Git.Switch>`, `<Git.Add>` and staged-only `<Git.Commit>` left that list when
278+
#294 shipped them as Workspace-local durable effects, and #297 shipped the
279+
shared Git-host reconciliation the remote effects are built over. What still
280+
resolves to nothing is what reaches a remote or a forge, plus the Agent ceiling
281+
and the constrained evaluator.
282+
279283
`<Repository>`, `<Worktree>` and `<Dir>` have left that list:
280284
`@executablemd/workflow/composition` registers all three (#293, shipped), which
281285
is what makes the composition below executable under a workflow run. Because
@@ -320,7 +324,7 @@ whose dependency order this workflow consumes in the same sequence.
320324
| foreground `xmd workflow start` / `resume` with an implicit Workspace and declarative `<File>` effects | #366 | shipped |
321325
| read-only `status`, `list` and `history` over immutable lifecycle snapshots | #367 slice 1, delivered by #460 | shipped |
322326
| 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 |
327+
| durable suspension, and releasing the executor lock back | #367 slice 3, delivered by #475 | shipped |
324328
| versioned history checkpoints, compatible forks, `history --forkable` and forkability reasons | #368 | open |
325329

326330
`xmd workflow start` is what makes this document a workflow rather than a script,
@@ -335,31 +339,31 @@ selects a previous run — replaying completed work and continuing the partial
335339
remainder. Both are Deno-entrypoint and compiled-binary capabilities; the Node
336340
and Bun entrypoints parse the grammar and refuse.
337341

338-
What the command does *not* supply is a checkout to run in or a way to reach a
339-
repository component: the run's Workspace starts empty until #293, and a pinned
340-
definition is executed with no repository component search path, so the stage
341-
components beside this one — `InstructionFiles`, `Discovery`, `UserCheckpoint`,
342-
`Planning`, `Implementation` — resolve to nothing under `xmd workflow start` and
343-
`xmd workflow resume`, and are exercised under `xmd run` instead.
344-
345-
That gap belongs to #301, in the "compose and certify" table below. It owes the
346-
authority and identity outcome rather than a spelling: `InstructionFiles`,
347-
`Discovery`, `UserCheckpoint`, `Planning`, and `Implementation` become reachable
348-
under `xmd workflow start` and `xmd workflow resume` from component code the
349-
trusted host authorized, with workflow-definition identity and retained-history
350-
admission accounting for that code, so resume and replay cannot substitute
351-
mutable checkout content for it and unauthorized or incompatible code is refused
352-
before it runs. `xmd run` resolution is unchanged, and no generic repository
353-
component search path is introduced for workflow execution. The mechanism is
354-
#301's to design, and it remains subject to architecture review there.
342+
The command supplies the checkout, and a root reaches its stages by declaring
343+
them. A workflow run still searches no repository directories at all; instead
344+
`start.md` closes itself over a **component bundle** in its own frontmatter, and
345+
`xmd workflow start` and `xmd workflow resume` resolve exactly those five names
346+
from the blobs the pinned definition commit holds (#493, shipped, delivering
347+
#301's component-bundle slice).
348+
349+
Identity is what the bundle buys. Each declared name normalizes to a canonical
350+
repository-relative path and the blob's own object ID, and those entries join
351+
workflow-definition identity and retained-history admission — so changing what a
352+
stage says makes a different definition, and a resume or a replay reconstructs
353+
the component from its retained source rather than from a mutable checkout. A
354+
same-named file beside the definition answers nothing, an undeclared name
355+
resolves to nothing at all, and ordinary `xmd run` resolution is unchanged.
356+
357+
What #301 still owes is the supervised composition itself: scheduling the loop
358+
and continuing it unattended. Reachable stage names are not a running workflow.
355359

356360
**2. Repository and deterministic Git composition.**
357361

358362
| Capability | Issue | Status |
359363
| --- | --- | --- |
360364
| `<Repository>`, self-closing `<Worktree>`, and the lexical `<Dir>` boundary that consumes a bound checkout path | #293 | shipped — registered by the workflow host |
361-
| `<Git.Switch>`, `<Git.Add>`, staged-only `<Git.Commit>` | #294 | open |
362-
| shared external forge-effect reconciliation | #297 | open |
365+
| `<Git.Switch>`, `<Git.Add>`, staged-only `<Git.Commit>` | #294 | shipped |
366+
| shared Git-host effect reconciliation | #297 | shipped — one request-only surface; the components over it are not |
363367
| explicit `<Git.Push>` | #370 | open |
364368
| `<PullRequest>` over an explicitly pushed head | #295 | open |
365369
| provenance-linked deferred `<Issue>` | #296 | open |
@@ -416,8 +420,9 @@ replay expands the same fragment without asking the Agent again.
416420
| namespaced document props | #305 | shipped |
417421
| synchronize this living target with settled contracts | #292 | this change |
418422
| prove the shipped planning-document logic | #290 | this change — the proof lands here; #290 closes on delivery |
419-
| compose the supervised workflow, and make its stage components reachable under `start` and `resume` | #301 | open |
420-
| resume from explicit durable signals | #300 | open |
423+
| a root's declared component bundle, resolved from its pinned commit | #301 slice, delivered by #493 | shipped |
424+
| compose the supervised workflow — scheduling the loop, continuing it unattended | #301 | open |
425+
| typed durable answer delivery to a suspended run | #300 | shipped — delivery is non-executing; automatic scheduling is not shipped |
421426
| default-on secret rejection before journal persistence | #199 | open — guard and scanner built |
422427
| certify interruption, replay, authority, reconciliation, and cross-runtime behavior | #299 | open |
423428

‎workflows/adversarial-implementation/runtime.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -151,9 +151,10 @@ the foreground process, and Ctrl-C tears the scope down in order, publishes
151151
management host acquires the lock and publishes `cancelled` inside the
152152
transaction that validates it.
153153

154-
What is still missing is the wait itself: durable suspension, and releasing the
155-
executor at a checkpoint, remain #367 and unbuilt; forks and forkability remain
156-
#368.
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.
157158

158159
## Cleanup follows the invocation
159160

@@ -178,10 +179,12 @@ An automated iteration stops on the first applicable signal:
178179

179180
Signal 3 has a shipped in-run form: `<Elicit>` asks a person a schema-validated
180181
question during execution, and under `xmd run` the WebForm provider answers it
181-
in a browser. Under `xmd workflow` the same question is to become a durable
182-
suspension, which waits on #367. Arbitration between signals is not implemented
183-
([#300](https://github.com/taras/executable.md/issues/300)), and premature
184-
watcher semantics are deliberately excluded from 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.
185188

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

0 commit comments

Comments
 (0)