📁 Give a workflow run's document its own filesystem (#366 PR 1) - #426
Merged
Conversation
tarasforce-pushed
the
agent/issue-366-workflow-cli
branch
from
August 10, 2026 14:31
9010005 to
20b7034ComparePR #426: 📁 Give a workflow run's document its own filesystem (#366 PR 1)25 files, +4280 / -229 Scope🔴 PR has 4509 lines changed. Split into focused PRs. 🟡 4509 lines changed. PRs under 400 receive more thorough review. 🟡 25 files changed. Are all changes related? 🟡 Changes span 7 directories. StructuralOxlint structural signals:
Slop✅ Slop indicators look low. Static AnalysisOxlint: 11 diagnostics across 7 files (7 rules) no-shadow (2): packages/workflow/src/deno/workspace/private.ts CorrectnessFILE: packages/workflow/src/deno/workspace/private.ts, PATTERN: no-shadow, CONCERN: Shadowing variable in same scope, QUESTION: Is the shadowed variable intentional or a mistake? |
4 tasks
taras
commented
Aug 10, 2026
OwnerAuthor
tarasforce-pushed
the
agent/issue-366-workflow-cli
branch
from
August 10, 2026 17:42
bdcb258 to
2adfc45Compare
This was referenced Aug 10, 2026
tarasforce-pushed
the
agent/issue-366-workflow-cli
branch
from
August 11, 2026 02:13
15c24ff to
c6dbdafComparetaras
marked this pull request as ready for review
August 11, 2026 02:16
4 tasks
taras
marked this pull request as draft
August 11, 2026 16:19
tarasforce-pushed
the
agent/issue-366-workflow-cli
branch
from
August 11, 2026 16:32
c6dbdaf to
9e86cebCompare`xmd workflow` needs a document filesystem that belongs to the run rather
than to whoever invoked the CLI. Until now the only Workspace mutation
path was adapter-private: `<File>` and `<Glob>` had no way to reach a
run's Workspace, so a workflow document would have written into the
caller's directory with nothing retained and nothing to resume from.
`withWorkflowWorkspace(database, operation)` installs a run's Workspace
effect coordinator, the logical working directory `/`, and a
transaction-bound `API.Files` provider — inside the execution, so they
answer ahead of the host adapter. It is the only installation the
entrypoint publishes: the three pieces are one authority boundary.
A run is attached through `ExecutionInstallation` values a trusted host
passes to `executeInstalled()`. Run identity is a mandatory admission
canonical core captures before any installation, middleware or document
code exists and applies inside its own trusted journal read. Creating or
restoring the run is the installation's `prepare` hook — the trusted
durable preparation core invokes inside the durable root, after
admission and before any public `Execution.document` policy, the root
import and every authored effect. No public middleware carries
workflow-run authority: a handler that answers without delegating
cannot fabricate a run, and a substitute result replaces nothing.
The run a document reads is published through a slot `install()` creates
per invocation, so a host holding one installation value and running two
documents with it gets two runs and neither execution can see the
other's. Nothing is read back out of that slot to authorize retained
history, select the durable run or decide agreement — the captured
`RunPreparation` and the durable record decide all three.
`retainedWorkflowInstallation(run)` records the exact frozen
`{ runId, base, pinnedCommit }` a host already created, allocates
nothing and never calls `Git.revParse()`.
Because #433 binds a terminal created before the root import to the
exact root source and target it was about, a preparation that failed —
a base that will not resolve — now replays as the failure it was rather
than as a history this version cannot read. The workflow specification's
§6 limitation is removed rather than recorded.tarasforce-pushed
the
agent/issue-366-workflow-cli
branch
from
August 11, 2026 16:52
9e86ceb to
6a3403cComparetaras
marked this pull request as ready for review
August 11, 2026 16:56
Uh oh!
There was an error while loading. Please reload this page.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import, through the same host-service slot `xmd run` fills with a real adapter. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
4 tasks
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does.
taras added a commit
that referenced
this pull request
Aug 11, 2026
`xmd workflow start <definition>` creates a run from committed Git bytes and executes it; `xmd workflow resume <run-id>` continues one from its retained definition and metadata rather than from whatever the checkout holds now. A start may name its own id with `--id`, and reuses a compatible run rather than creating a second one. The run reaches canonical core the way #426 and #433 settled: as an `ExecutionInstallation` the trusted host passes to `executeInstalled()`, carrying the retained-run admission core applies inside its own journal read and the `prepare` hook it invokes inside the durable root. One execution, not an installed call followed by an ordinary one — `xmd run` and `xmd test` pass an empty installation list, which is exactly what `execute()` already does. A run that ended is not a run to continue. `resume` admits interrupted, suspended and — as a full replay — completed; failed and cancelled are refused before the definition is fetched, before an orphaned execution is closed, before a record is begun, before a Workspace is attached and before anything is appended. Reusing a compatible id through `start` still replays a failed run's retained failure; that is a separate rule. A status line says what was retained, so it is published only once both lifecycle writes have persisted — the completion record, then the run state. The first refusal is the answer: the intended status is neither published nor claimed, the invocation exits 1, and a document failure that also occurred is still reported. An explicit lifecycle phase keeps a post-execution storage refusal from being republished as a host interruption. The definition is pinned to a Git object, so an uncommitted edit beside it never runs. A component search path would read that mutable checkout, so there is none. Service denial is installed in the execution's own scope, before the root import. A run's Workspace is attached only for live and partial work: a completed replay has a recorded root result and is given no filesystem to open a transaction against. Node and Bun refuse to host a workflow with one settled sentence, before reading a definition or creating a store, while rendering the same grammar every host does. Co-authored-by: Taras Mankovski <74687+taras@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
xmd workflowneeds a document filesystem that belongs to the run rather than towhoever invoked the CLI. Until now the only Workspace mutation path was
adapter-private:
<File>and<Glob>had no way to reach a run's Workspace, soa workflow document would have written into the caller's directory with nothing
retained and nothing to resume from.
This is PR 1 of a two-PR stack for #366, rebased onto #433. It builds the
provider layer and the run installation the CLI composes over. PR 2 (#428) adds
xmd workflow start/resume, the Git definition adapter, cross-processacceptance tests, and closes#366.
What changes
Before:
API.Fileshad one provider — the host adapter every entrypoint installs. TheDeno Workspace coordinator existed, but only an adapter-private proof
operation selected it and
<File>could not reach it.resolved its own base, which a host that already created the storage record
cannot use: the id it invents cannot agree with the record.
After:
withWorkflowWorkspace(database, operation)installs a run's Workspace effectcoordinator, the logical working directory
/, and a transaction-boundAPI.Filesprovider — inside the execution, so they answer ahead of the hostadapter. A document's
<File>and<Glob>then name entries in the run's ownlogical filesystem. It is the only installation the entrypoint publishes.
workflowInstallation({ base })andretainedWorkflowInstallation(run)areExecutionInstallationvalues a trusted host passes toexecuteInstalled().Each contributes a mandatory admission and a
preparehook; neitherinstalls any
Execution.documentmiddleware. The retained one records theexact frozen
{ runId, base, pinnedCommit }, allocates nothing, and nevercalls
Git.revParse().xmd run,xmd testand the host provider are untouched. No CLI reaches any ofthis yet.
Where run identity is decided, and where the run is created
Two different places, and neither is middleware.
Identity is a mandatory admission. Canonical core captures it before any
installation, middleware or document code exists, and applies it inside the same
trusted
readAllthat already holds a resumed run to its recorded rootselection — on the one retained snapshot every later phase reads.
Creation and restoration are the installation's
preparehook — aDurablePreparationcore invokes inside the durable root, after admission andbefore any public
Execution.documentpolicy, the root import and everyauthored effect. On a completed terminal replay core never enters the durable
body, so preparation does not run and the admission is what restores the run; on
a partial continuation preparation re-enters and its durable operation restores
what it already recorded, so neither the identifier nor Git is reached again.
Earlier revisions of this PR put identity in
ReplayGuard, then in anExecution-installed stream wrapper, and kept creation inExecution.documentmiddleware. All three were defeated by registration order, which is what
motivated #432 and #433. None of that machinery lives here any more.
A record identifies a run only as the root coroutine's successfully settled
Yield, under the canonical type and name, holding a closed value of exactly
runId,baseandpinnedCommit, agreeing with the installed identity. Anyhistory with events must carry at most one; a retained installation requires
exactly one, and a successful one.
A definition's exact document target (#431) is not identity. It says what the
run is a run of. A recorded value carrying a target as a fourth member is
refused as a value this version cannot account for, and the target is never
quoted back (RR23).
The slot is per invocation, not per installation value
install()runs once for each execution an installation value is passed to, andthat is where the slot is created. An earlier revision built it alongside the
value, so a host holding one
workflowInstallation({ base })and running twodocuments with it gave both the same slot: each journal recorded its own run,
and both documents read whichever ran last. WR20 reproduces exactly that and
fails against it.
Admission and preparation reach the slot installed for their own invocation when
they run. Nothing is read back out of it to authorize retained history, select
the durable run or decide agreement — the captured
RunPreparationand thedurable record decide all three, and the slot is only where the answer is
published.
One shape change the lifecycle forced
getWorkflowRun()reads a slot the installation puts in the execution'sscope, and the stable
executablemd.workflow.runbinding now holds that slotrather than the run itself (WR17 asserts a foreign descriptor still reaches the
same frozen run, under
run).This is not a preference. Both writers now sit outside the scope that reads
them: admission runs inside core's own journal read, and preparation runs inside
the durable root. A context set from either ends with the operation that set
it, while the document that has to read it starts afterwards. The slot is the
same pattern core uses for
LiveFailure. The binding was already explicitlynon-authoritative — a descendant may rebind the name, and durable enforcement
never depends on it — and that reasoning is unchanged.
Review guide
Start with:
packages/workflow/src/deno/workspace/files.tsspecs/workflow-spec.md§3.1, §3.2 and §10 — the contracts this adds.packages/workflow/src/run.ts— the two installation constructors, and therequirement each contributes.
packages/workflow/src/journal.ts— canonical-record recognition, and therefusals that name differing fields without their values.
packages/workflow/src/deno/workspace/logical-path.ts— why containment hereneeds no stable-namespace qualification.
packages/workflow/src/deno/workspace/host.ts— what a host installs, and whythe three pieces are not published separately.
Look carefully at:
files.ts. A refusal is retained as a phase and areason, never as a serialized error — no DOFS message, errno payload, SQLite
text or resolved path reaches the journal.
parseOutcome. Journal data is untrusted: a record must carry its variant'smembers and no others, each of the declared type, and a refusal's phase and
reason must be words the operation's vocabulary holds. Everything else is the
fixed cause-free
FilesInvariantError("protocol").writeOutcome: the mutation savepoint wraps parent creation and the write,so a refusal discards partial mutation before the sanitized result is
published.
descend: a search answers with regular files, on HF3's contract. A symboliclink is neither a result nor a way into the tree it names.
What must stay true
installed at
{ at: "min" }inside the execution, and a hostAPI.Filesobserver installed outside the run stays empty in every WF test.
<Glob>answers the same way under either provider — regular files only(WF11 mirrors HF3).
whose recorded value is read back (WF4, WF5).
RR14, RR20, RR21) and for every file outcome (WF13).
RR17; RR12 and RR13 show valid replay and valid policy still compose.
withWorkflowWorkspace()is the only one exported frompackages/workflow/deno.ts.Verification
6a3403cf6da12ec529920122b3b8841bda0f3add, rebased ontomainatf4e3eee(#434, which carries the merge of #433):
Mutations
Each applied, the suite re-run, the source restored from
HEADand confirmedbyte-identical before the next.
descenddrops theentry.kind !== "file"skipdescendwalks through symlinks as well as directoriesparseOutcomedrops the exact-members checkparseOutcomefalls back instead of refusing an unknown phase or reasonwriteOutcomecallsreplace(...)without the nested savepointresolveLogicalPathstops refusing an empty pathhost.tsdoes not installuseWorkflowFileseffect.tsskipsvalidateJournalProvenance(...)contentis coerced instead of type-checkedExecution.documentmiddlewarepreparehook removed from the installationinstall()Four honest limits:
that removes only the admission leaves it green. RR8/RR14/RR15 cover what the
admission alone decides.
FilesInvariantError("protocol")with a generic causederror fails nothing.
invokeFilesinpackages/core/src/files.tsalreadynormalizes any non-Files provider throw into a fresh cause-free protocol
invariant, so the observable guarantee is core's and the provider's own throw
is defence in depth.
readWorkflowRunthrow its own exception fails nothing,because
retainEventsrebuilds a recorded value before anything reads it —runClaim's catch is the real converter, and Q4 covers the host-supplied side.20b7034, where "reads thecurrent frontier instead of the recorded result" killed them. That machinery is
unchanged by the rebase and no mutation re-run here covers it.
Scope
Included
API.Filesprovider over the run's logical DOFS Workspace.withWorkflowWorkspace()— coordinator, logical cwd/, provider — as thesingle public installation boundary.
workflowInstallation()/retainedWorkflowInstallation()asExecutionInstallationconstructors.parseFilesReason/parseFilesPhase/parseFileWritePhaseexported from@executablemd/runtime, so a provider reading a retained refusal parses theone vocabulary rather than declaring a second copy.
Intentionally unchanged
xmd workflowdoes not exist yet.xmd runandxmd testkeepuseHostFiles()exactly as they had it.as a failed effect and that history is still this run's, so no successful
record is demanded of it (WR18).
remain unbuilt.
JournalProvenancestays at its existing trusted wrapping sites; this PR addsnone.
Rebase notes
packages/core/src/journal-admission.tsand theadmitJournal/requiredJournalAdmissionsexports are removed — 🔒 Make canonical core authoritative for execution #432 replaced them, and🔒 Make canonical core authoritative for document expansion #433 replaced the document-middleware half.
Execution.execute(options)signature and now usenext(request.withOptions({ ...request.options, stream })).workflowInstallation; the API name changed by design, so those expectationsare contract maintenance rather than a test edited to pass.
Scope confirmation