You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0a60328
Browse filesBrowse the repository at this point in the historyBrowse files
`<File>`, `<Glob>` and `<TempDir>` reached the host filesystem directly, so
`xmd run` and a workflow run could not mean the same thing for one document.
Document filesystem access now goes through `API.Files`, a contextual Api of
whole semantic operations with no host default. The four CLI entrypoints
install the host provider explicitly; a run with none installed fails rather
than reaching the host.
The three components make no filesystem call of their own and import no host
path or fs module. What they keep is order: a write's lexical check runs before
its children, and the semantic write that follows repeats admission and owns
every later phase, so the earlier check authorizes nothing.
Ordinary failures cross the boundary as frozen structural data — a reason from
a fixed vocabulary and the phase it came from — and every printed message is
byte-identical to before. A provider that is absent, refuses an operation, or
breaks its own contract throws instead, and core's fatal traversal ranks it
between a durability failure and a documentation failure, by identity and by
structural tag.
Copy file name to clipboardExpand all lines: architecture.md
+57-1Lines changed: 57 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,6 +42,10 @@ Existing documents and code get aligned to this section retroactively.
42
42
| blocker | execution needs input (auth, a human answer); not a failure |
43
43
| suspension | a durable wait: a crash restarts into the same wait |
44
44
| Workspace | the provider-neutral, run-owned environment that supplies retained filesystem, repository, process and working-directory capabilities to a workflow |
45
+
| document filesystem | the files a document names in its own text, reached only through `API.Files`; distinct from the host paths the engine's own control plane reads |
46
+
| Files provider | the installed implementation of `API.Files` for a document execution: the host provider under `xmd run`, a transaction-bound provider under a workflow run. There is no default, and no provider falls back to another |
47
+
| stable host namespace | the condition the host Files provider's containment is stated under: no other process replaces a directory, symlink, junction or reparse point between the moment a path is observed and the moment it is used |
48
+
| Files infrastructure failure | a Files provider that is absent, that refuses an operation, or that broke its own contract; fatal like a durability failure, and never a printed error |
45
49
| ephemeral | a replay classification for an operation, context or attachment that runs again to reconstruct live execution; its result is not substituted from the journal and it owns no durable workflow state |
46
50
| live binding | an execution-owned value reconstructed ephemerally for the current document execution; it is visible only to constructs that explicitly consume the live binding overlay and never enters interpolation or the journal |
47
51
| attached service | a scoped host process that publishes its authenticated loopback endpoint through the XMD service handshake protocol and remains supervised for the lifetime of its service attachment |
@@ -688,7 +692,7 @@ the process may terminate, and a later document execution arrives back at the
688
692
same wait. An error that reveals a blocker (an expired login) reaches suspension
689
693
through middleware; waiting itself is never raised.
690
694
691
-
### 8. Durability failures are outside the model
695
+
### 8. Durability and Files infrastructure failures are outside the model
692
696
693
697
A durability failure (§6.11) says the journal no longer describes the document
694
698
execution. No middleware sees it; it is never the document's own outcome. A
@@ -705,6 +709,55 @@ throws. A pre-persistence policy rejection remains the policy's ordinary
705
709
document failure; the guarded stream marks that boundary before the backing
706
710
append and does not activate the fail-stop state.
707
711
712
+
A Files infrastructure failure is outside the model on the same terms. A
713
+
missing provider, a refused operation, and a provider that broke its own
714
+
contract are none of them things the document did or can act on, and printing
715
+
one would let every step after the file work run as though the file work had
716
+
happened. No middleware converts one, and no printing boundary prints one.
717
+
718
+
Both are discovered through one cycle-safe traversal of the whole cause graph,
719
+
and precedence is decided by kind rather than by position: a durability failure
720
+
first, then a Files infrastructure failure, then a documentation failure. The
721
+
selected failure comes back by identity, because a fail-stop that records "the
722
+
first error" has to record the one that happened. Recognition is structural —
723
+
a stable tag on frozen data, never `instanceof` — so a failure a separately
724
+
loaded copy constructed is found on the same terms as one this copy did.
725
+
726
+
## The document filesystem boundary
727
+
728
+
Contextual routing is not authority. `API.Files` decides *which* provider
729
+
answers a document's file operations; what a provider is allowed to do is
730
+
decided by the provider, from identities the contextual layer cannot supply.
731
+
732
+
The Api's operations are whole semantic acts — read this path, replace this
733
+
path, list what these patterns select — rather than steps a caller sequences.
734
+
The one preliminary operation, `checkFilePath`, is deliberately weak: pure path
735
+
arithmetic, no filesystem access, and it returns nothing usable. `<File>` calls
736
+
it to decide whether a write's children may expand, and the later write repeats
737
+
the same admission from the same authored path. Nothing is handed between them,
738
+
so a check that was skipped or answered elsewhere authorizes nothing.
739
+
740
+
The two providers make different containment claims, and both are stated rather
741
+
than implied:
742
+
743
+
-**`xmd run`** resolves document paths in the caller's own filesystem. It
744
+
refuses empty, absolute, and lexically escaping paths without touching the
745
+
filesystem, and refuses an observed outward symlink once resolution can see
746
+
one. That holds while the host namespace is stable; it is not a sandbox, and
747
+
closing the replacement window would require a native dependency this project
748
+
does not take.
749
+
-**A workflow run** resolves document paths in the run-owned Workspace's
750
+
logical filesystem, inside the caller-owned transaction. A document path
751
+
never becomes a host path, so there is no host namespace to replace.
752
+
753
+
Neither claim covers a native command a document runs.
754
+
755
+
Failure data crosses the boundary as a plain frozen object under a stable tag,
756
+
carrying a reason from a fixed vocabulary and the phase it came from. No
Consumers parse that data before reading a field; a write whose data does not
759
+
validate is a provider-contract failure rather than a commit state to invent.
760
+
708
761
## Attempts
709
762
710
763
- The journal records every attempt in full; replay restores the outcome
@@ -831,6 +884,9 @@ Status is measured against main.
831
884
| Workspace coordination API | fails closed by default and lets a Workspace operation explicitly select provider coordination | built on the #365 stack; the atomic Deno Workspace handler is unbuilt |
832
885
| explicit WorkflowRun journal route | binds one already-filtered publication to one exact active transaction and otherwise uses ordinary serialized journal storage | built on the #365 stack |
833
886
|`API.Service` / `startService()`| creates an authenticated, supervised loopback service attachment through a provider-neutral operation | built on main |
887
+
|`API.Files`| routes every document filesystem operation to the installed provider, with no host default and structural failure data | built on the #227 stack |
888
+
| host Files provider / `useHostFiles()`| resolves document paths in the caller's filesystem, containing them while the host namespace is stable; installed by all four CLI entrypoints | built on the #227 stack |
889
+
| transaction-bound Files provider | resolves document paths in the run-owned logical Workspace inside the caller-owned transaction | unbuilt; the adapter is #227's second layer, and workflow effect coordination and CLI reachability remain unbuilt |
834
890
|`service=<binding>`| publishes the attachment's endpoint into the live binding overlay for its invocation | built on main |
835
891
|`ephemeral eval`| reconstructs live middleware and bindings without a journal entry | built on main |
836
892
|`useWorkflowServiceDenial()`| provides and tests a non-delegating workflow service denial provider; #366 will install it in future start and resume scopes | built on main; no workflow CLI execution branch exists yet |
0 commit comments