Skip to content

Commit 7c1fd4a

Browse files
committed
📝 Compose the checkout path and the directory it is worked in
The flow bound its worktree with a lexical `<Worktree as="worktree">` and expected that same invocation to render the stages inside it. Generic `as=` is an ordinary private capture, and #293 settled that Repository and Worktree get no exception to it — so that spelling would have captured the whole flow and left the root's `<Output>` with nothing to emit. The two existing forms compose instead: a self-closing `<Worktree … as>` creates or restores the retained checkout and binds its path, and a lexical `<Dir path={worktree}>` inside the same `<Repository>` makes that path cwd, renders the stages and the final report, and restores the enclosing cwd. Agent access is still `<Agent.AddDir>`; cwd never implies it. `<Dir>` is not built either, so the unresolved inventory is ten names rather than nine, and #293 owns the boundary this composition consumes. Reading a run back is no longer future work. `xmd workflow status`, `list` and `history` report immutable lifecycle snapshots — no lease, no replay, no Workspace, no append — so the documents say so, and say what history actually prints: an authored source position rather than a forkability reason it does not have. Suspension, executor ownership, cancellation and deletion stay #367; forks and forkability stay #368.
1 parent c2e5635 commit 7c1fd4a

6 files changed

Lines changed: 164 additions & 72 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 46 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -87,10 +87,11 @@ frontier, releases the executor, and reports the run ID and stop reason;
8787
`xmd workflow resume` continues there once the answer is available. Neither the
8888
process nor the Agent sessions need to stay alive in between. `xmd workflow
8989
start` and `xmd workflow resume` are shipped (#366), and a resume continues from
90-
the retained frontier; what is not built is the boundary itself — a checkpoint
91-
that releases the executor, the ownership that decides who may continue a run,
92-
and the stop-reason inspection that reports why it stopped are #367.
93-
`<Stage>` is not the answer: it was
90+
the retained frontier; `xmd workflow status` reports a stopped run's retained
91+
status and stop reason without advancing it (#460). What is not built is the
92+
boundary itself — a checkpoint that releases the executor, and the
93+
single-executor ownership and atomic lifecycle transitions that decide who may
94+
continue a run, remain #367. `<Stage>` is not the answer: it was
9495
rejected as architecture, because the root document is the workflow and a durable
9596
run may continue through several document executions without inventing
9697
subdivisions between them (#298, closed).
@@ -444,14 +445,24 @@ implicit workspace:
444445

445446
- `<Repository>` authorizes a Git locator, resolves an optional base once, pins
446447
that commit, and creates the named primary checkout inside the run's Workspace.
447-
`<Worktree>` adds a named linked checkout on its own branch. Both install
448-
contextual cwd while rendering their children and bind their Workspace-relative
449-
path through `as` (#293). Names are stable component identity, not lookup keys
450-
into hidden configuration: a locator and a base are ordinary root props or
451-
expressions. Two repositories are two `<Repository>` elements, and no
452-
transaction spans them.
453-
- `<Dir>` is lexical cwd and nothing else. Making a directory readable by an
454-
Agent is `<Agent.AddDir>` (#302), a separate operation on purpose.
448+
A self-closing `<Worktree … as>` adds a named linked checkout on its own branch,
449+
creating or restoring it, and binds its Workspace-relative path (#293). Names
450+
are stable component identity, not lookup keys into hidden configuration: a
451+
locator and a base are ordinary root props or expressions. Two repositories are
452+
two `<Repository>` elements, and no transaction spans them.
453+
- Binding a checkout path and running work under it are separate steps, and that
454+
is settled rather than stylistic. A generic component invocation written with
455+
`as=` is an ordinary private capture, and `<Repository>` and `<Worktree>`
456+
receive no exception to it, so a lexical `<Worktree … as>…</Worktree>` cannot
457+
both bind the path and render its children — it would capture them. A workflow
458+
that needs both composes the self-closing form with a lexical
459+
`<Dir path={…}>` inside the same `<Repository>`.
460+
- `<Dir>` is lexical cwd and nothing else: it establishes a bound path as cwd for
461+
its children, renders them normally, and restores the enclosing cwd when it
462+
closes. Making a directory readable by an Agent is `<Agent.AddDir>` (#302), a
463+
separate operation on purpose, and cwd never implies it. `<Dir>` is unbuilt,
464+
and #293 owns the boundary this composition consumes unless an earlier issue
465+
supplies it first.
455466
- `<Git.Switch>`, `<Git.Add>` and staged-only `<Git.Commit>` operate on the
456467
contextual checkout as Workspace-local durable effects (#294). `<Git.Push>` is
457468
explicit and separate (#370), and `<PullRequest>` requires that pushed head
@@ -564,13 +575,25 @@ session, terminal status, text, and structured failure. `<Elicit>` journals its
564575
validated answer keyed by a fingerprint of the compiled schema and the rendered
565576
message, and refuses a recorded answer whose question does not match.
566577

567-
`xmd workflow history` is how a person reads that back: stable public event IDs
568-
with each event's operation, source location, normalized evaluated arguments,
569-
result or normalized error, Workspace version, and forkability reason. It is
570-
read-only — it attaches no Workspace, Agent, or external provider and cannot
571-
advance a run — and it exposes no value the security policy has not already seen.
572-
That surface, with `status`, `list`, cancellation and deletion, is #367 and is
573-
unbuilt.
578+
`xmd workflow history <run-id> [--json]` is how a person reads that back: stable
579+
public event IDs with each event's operation, authored source position, result or
580+
normalized error, and Workspace root. It is shipped, with
581+
`xmd workflow status <run-id> [--json]` and
582+
`xmd workflow list [--status=<status>] [--json]`, as #367's first slice (#460).
583+
584+
Each answers from an immutable lifecycle snapshot, and what it refuses to do is
585+
the contract: no execution handle and no executor lease, no replay and no
586+
advancement, no Workspace attachment and no root materialization, no document
587+
import, no Agent, process or external provider, and no reconciliation or append.
588+
History reads already-filtered retained protocol events, so it exposes no value
589+
the security policy has not already seen, and the authored source position it
590+
reports is descriptive evidence about an event rather than identity.
591+
592+
The rest of the lifecycle is not built. Durable suspension and releasing the
593+
executor at a checkpoint, the single-executor ownership and atomic lifecycle
594+
transitions around them, and cancellation and deletion remain #367; versioned
595+
history checkpoints, compatible forks, `history --forkable`, and forkability
596+
reasons remain #368.
574597

575598
**Still missing: who answered.** The journal records the validated decision, the
576599
question fingerprint, and the document execution it belongs to. It does not
@@ -896,8 +919,10 @@ shipped behavior. They are recorded because the answers constrain what remains.
896919
The exercise must resolve enough of these to implement one vertical slice:
897920

898921
1. How does `<Worktree>` choose an idempotent identity, branch name, and cleanup
899-
policy from the Repository base the run already pinned, and what does a
900-
provider without native worktree semantics present instead (#293)?
922+
policy from the Repository base the run already pinned; what does a provider
923+
without native worktree semantics present instead; and how does the lexical
924+
`<Dir>` boundary that consumes a bound checkout path replay without recreating
925+
a completed checkout effect (#293)?
901926
2. What does a read-only Agent receive, and how is the ceiling proven for each
902927
provider before a Prompt runs (#302)?
903928
3. What is the public spelling and response schema of the constrained

‎workflows/adversarial-implementation/Planning.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,8 @@ Every `plan`, `verdict`, and `planCheckpoint` is already durable: each `<Prompt>
304304
is one durable operation, each `<Elicit>` answer is journaled against its
305305
question fingerprint, and under `xmd workflow` those filtered events are retained
306306
with the run and resumable from it (#291 and #366, shipped), and readable through
307-
`xmd workflow history` once that surface exists (#367, open). There is no `cancelled` loop outcome — run-level cancellation and stop
307+
`xmd workflow history` (#367's first slice, delivered by #460), which reports
308+
them without advancing the run. There is no `cancelled` loop outcome — run-level cancellation and stop
308309
reasons are retained run state rather than loop state. The component creates no
309310
handoff files either way.
310311

‎workflows/adversarial-implementation/artifacts.md‎

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -108,25 +108,40 @@ what makes an event selectable for a history fork later (#368).
108108
## Reading the history
109109

110110
`xmd workflow history <run-id>` exposes stable public event IDs with each
111-
event's operation, source location, normalized evaluated arguments, result or
112-
normalized error, Workspace version, and forkability reason:
111+
event's operation, authored source position, result or normalized error, and
112+
Workspace root:
113113

114114
```text
115-
EVENT OPERATION ARGUMENTS RESULT WORKSPACE FORKABLE
116-
E14 File path="docs/notes.md" completed V7 yes
117-
E15 Agent.Prompt prompt=<filtered> <summary> V7 no: provider has no checkpoint
118-
E16 Git.Add paths=["docs/notes.md"] completed V8 yes
119-
E17 Git.Commit message="Document the workflow" 6f21a9… V9 yes
115+
EVENT OPERATION SOURCE RESULT WORKSPACE
116+
E14 File start.md:31:5 completed V7
117+
E15 Agent.Prompt Discovery.md:23:7 <summary> V7
118+
E16 Git.Add Implementation.md:207:7 completed V8
119+
E17 Git.Commit Implementation.md:208:7 6f21a9… V9
120120
```
121121

122-
Values come from the retained journal after its security filter, so history
123-
exposes nothing the policy has not already seen, and it never reconstructs a
124-
filtered value from the Workspace or the provider. `status`, `list`, and
125-
`history` are read-only: they attach no Workspace, Agent, or external provider,
126-
and cannot advance a run. That surface is
127-
[#367](https://github.com/taras/executable.md/issues/367) and is unbuilt.
128-
129-
Part of what it will read is already journaled. `<Loop>` records every iteration
122+
That surface is shipped ([#460](https://github.com/taras/executable.md/pull/460)
123+
delivering #367's first slice): `xmd workflow status <run-id> [--json]`,
124+
`xmd workflow list [--status=<status>] [--json]`, and
125+
`xmd workflow history <run-id> [--json]`.
126+
127+
What makes it safe to read a run someone else may be running is what it refuses
128+
to do. Each command answers from an immutable lifecycle snapshot: it takes no
129+
execution handle and no executor lease, performs no replay and advances nothing,
130+
attaches no Workspace and materializes no root, imports no document, contacts no
131+
Agent, process, or external provider, and reconciles and appends nothing. History
132+
reads already-filtered retained protocol events, so it exposes nothing the
133+
security policy has not already seen, and it never reconstructs a filtered value
134+
from the Workspace or the provider. The authored source position it prints is
135+
descriptive evidence about an event, never identity — nothing is located by
136+
reconstructing a position from an expansion ID, the current definition, or the
137+
Workspace.
138+
139+
There is no forkability column and no forkability reason. Selecting an event to
140+
fork from is #368, along with versioned history checkpoints and
141+
`history --forkable`, and none of it is built.
142+
143+
Part of what history reads is journaled by the constructs the workflow already
144+
writes. `<Loop>` records every iteration
130145
it enters and one terminal `break`, `exhausted`, or `error` outcome, and refuses
131146
a replay that disagrees with what this execution reached. Each `<Prompt>` is one
132147
durable operation carrying its identity, input, agent and session, terminal

‎workflows/adversarial-implementation/primitives.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -263,12 +263,13 @@ 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-
Nine names in this workflow resolve to nothing today, and each is owed by one
266+
Ten 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 |
272273
| `<Expand>` | #369 |
273274
| `<Git.Add>` | #294 |
274275
| `<Git.Commit>` | #294 |
@@ -278,6 +279,21 @@ issue:
278279
| `<Repository>` | #293 |
279280
| `<Worktree>` | #293 |
280281

282+
`<Dir>` joined that list with the composition #293 settled. A generic component
283+
invocation written with `as=` is an ordinary private capture — it binds its
284+
result and contributes nothing at the call site — and `<Repository>` and
285+
`<Worktree>` receive no exception to it. So a lexical
286+
`<Worktree … as="worktree">…</Worktree>` cannot mean "bind the path *and* render
287+
these children"; it would capture the flow, and the root's `<Output>` would emit
288+
nothing. A workflow that needs both composes the two existing forms: a
289+
self-closing `<Worktree … as="worktree" />` creates or restores the retained
290+
checkout and binds its Workspace-relative path without establishing cwd for what
291+
follows, and a lexical `<Dir path={worktree}>` beneath it makes that bound path
292+
cwd for the stage flow, renders its children normally, and restores the enclosing
293+
`<Repository>` cwd on the way out. Both sit inside the lexical `<Repository>`, so
294+
its context is present throughout. `<Dir>` registers nothing with an Agent —
295+
`<Agent.AddDir>` remains the explicit authorization, and cwd never implies it.
296+
281297
Everything else the workflow writes resolves: `<If>`, `<Else>`, `<Loop>`,
282298
`<Break>`, `<Each>`, `<Capture>`, `<Output>` and `<Return>` as structural syntax;
283299
`<Elicit>`, `<File>`, `<Glob>`, `<Parse>` and `<SafeParse>` as core defaults;
@@ -298,8 +314,9 @@ whose dependency order this workflow consumes in the same sequence.
298314
| open and look up one WorkflowRun database; append and replay the filtered journal | #291 | shipped |
299315
| commit a Workspace mutation, its logical root, and the journal result atomically | #365 | shipped |
300316
| foreground `xmd workflow start` / `resume` with an implicit Workspace and declarative `<File>` effects | #366 | shipped |
301-
| `status`, `list`, `history`, suspension, cancellation, deletion, single-executor ownership | #367 | open |
302-
| versioned history checkpoints and compatible forks | #368 | open |
317+
| 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 |
319+
| versioned history checkpoints, compatible forks, `history --forkable` and forkability reasons | #368 | open |
303320

304321
`xmd workflow start` is what makes this document a workflow rather than a script,
305322
and it exists: `xmd workflow start [--id] [--props-*] <definition>` creates the
@@ -335,7 +352,7 @@ component search path is introduced for workflow execution. The mechanism is
335352

336353
| Capability | Issue | Status |
337354
| --- | --- | --- |
338-
| `<Repository>` and `<Worktree>` as named Workspace composition, with lexical cwd | #293 | open |
355+
| `<Repository>` and self-closing `<Worktree>` as named Workspace composition, and the lexical `<Dir>` boundary that consumes a bound checkout path | #293 | open |
339356
| `<Git.Switch>`, `<Git.Add>`, staged-only `<Git.Commit>` | #294 | open |
340357
| shared external forge-effect reconciliation | #297 | open |
341358
| explicit `<Git.Push>` | #370 | open |

‎workflows/adversarial-implementation/runtime.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -130,9 +130,15 @@ document starts a new run.
130130
Two of the three are here. `start` and `resume` are shipped (#366): an
131131
interrupted run stays resumable at the journal frontier, a failed or cancelled
132132
run is refused before anything is fetched, attached or appended, and a resume of
133-
a completed run replays it in full. Suspension is not: releasing the executor at
134-
a checkpoint, the ownership that decides who may continue a run, and `status`,
135-
`list`, `history`, `cancel`, and `delete` are #367 and unbuilt.
133+
a completed run replays it in full. Reading a run back is shipped too —
134+
`xmd workflow status`, `list`, and `history` report immutable lifecycle
135+
snapshots, taking no executor lease, advancing nothing, attaching no Workspace,
136+
and appending nothing (#367's first slice, delivered by #460).
137+
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
141+
#368.
136142

137143
## Cleanup follows the invocation
138144

0 commit comments

Comments
 (0)