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 4b82bba
Browse filesBrowse the repository at this point in the historyBrowse files
A root document now catalogs its own addressable static headings, resolves one
selector to exactly one of them, and projects itself down to the preamble, each
ancestor's own content, and that section's subtree before anything expands.
Heading discovery parses a masked copy of the body, with the boundary scanner's
top-level component spans blanked to spaces of the same length. Remark ends the
HTML block it infers for a component at a blank line, so a component child's
`#` line surfaces as a root heading without the mask; offsets, lines, and
everything outside those spans are untouched, so the mask changes what is seen
and never where anything is.
Projection retains original source ranges and scans each one under its own
origin instead of concatenating and rescanning, so skipped source cannot
renumber what follows it and a retained element keeps its expansion ID.
The exact resolved target, never the caller's glob, is what the durable root
import records. A replay guard resolves the current selector against the
recorded content and requires the recorded exact target, in the check phase so
a completed journal cannot answer for a section it never ran.
`xmd targets`, targeted `xmd run`, and the targeted workflow definition are the
later layers of #412 and remain unbuilt.
Copy file name to clipboardExpand all lines: architecture.md
+37Lines changed: 37 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,6 +31,7 @@ Existing documents and code get aligned to this section retroactively.
31
31
| definition base | the Git revision supplied to choose a workflow definition's pinned commit |
32
32
| Repository base | the optional Git revision from which one named Workspace Repository initializes its primary checkout |
33
33
| pinned commit | the commit obtained by resolving a base once; it remains the workflow run's starting repository state even as the run creates descendant commits |
34
+
| document target | an addressable static heading in a root document's own Markdown flow, named by the canonical path of heading labels that reaches it; selecting one executes the preamble, each ancestor's own content, and that heading's complete subtree |
34
35
| expansion | one logical evaluation of an authored executable element within a document execution |
35
36
| expansion ID | a deterministic identifier for one logical expansion; restoring or retrying that expansion preserves the ID, while a distinct evaluation requested by the document receives another |
36
37
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
exposes no native executable or host PATH and is not described as POSIX or
600
601
native Bash.
601
602
603
+
## Document targets
604
+
605
+
A root document addresses its own sections. The outline is discovered from the
606
+
document's static Markdown alone: only headings in the root flow are targets,
607
+
and a heading is addressable only when its text is statically rendered — a
608
+
heading generated inside a component, or one carrying an interpolation, has no
609
+
stable address, and neither does anything beneath it. Discovery therefore
610
+
parses a copy in which the scanner's top-level component spans are blanked,
611
+
because a Markdown parser reading raw XMD cannot tell a component's children
612
+
from the root flow.
613
+
614
+
Selection resolves exactly once, before the document expands and before any
615
+
authored effect runs. A selector may glob, but it must name exactly one catalog
616
+
entry: naming none and naming several are both failures, and two sections that
617
+
canonicalize to the same path stay two entries so the ambiguity is reported
618
+
rather than resolved arbitrarily.
619
+
620
+
The selector and the target it resolves to are different things, and only one
621
+
of them is identity. A selector is invocation input — it describes what a
622
+
caller asked for, and two callers may spell the same request differently. The
623
+
**exact resolved target** is what ran, so it is what a document execution
624
+
records durably, what a targeted workflow definition carries, and what a resumed
625
+
run is checked against. A caller's glob is never recorded and never re-resolved
626
+
against a newer checkout; a resumed run re-resolves the current selector against
627
+
the *recorded* content and refuses to continue unless it still names the
628
+
recorded target.
629
+
602
630
## Expansion identity
603
631
604
632
Core describes the executable element currently being expanded:
@@ -635,6 +663,14 @@ JavaScript object identity.
635
663
document execution receives expansion identity without installing workflow
636
664
middleware.
637
665
666
+
Selecting a document target does not disturb any of this. Projection retains
667
+
the original source ranges and scans each one under its own origin, so a
668
+
retained element keeps the offset and line it was authored at, and with them
669
+
its expansion ID. Two runs of the same document under different targets
670
+
therefore agree on the ID of every element they both retain, and may share IDs
671
+
without sharing effects — run identity and workflow-definition identity are
672
+
what tell those runs apart.
673
+
638
674
## Two layers
639
675
640
676
Error handling has two layers:
@@ -956,6 +992,7 @@ Status is measured against main.
956
992
|`<PrintErrors>` / `printErrors(fn)`| prints failures | built on main |
957
993
|`<Output>` region `output` mode | an undecided error fails the document execution | built on main |
958
994
|`Expansion` / `getExpansion()`| describes the current logical element expansion | built on main |
995
+
| document targets | catalogs a root document's addressable static headings, resolves one selector to one exact target, and projects the document to it before expansion | built on the #412 stack; `xmd targets`, targeted `xmd run`, and the targeted workflow definition are unbuilt |
959
996
|`useWorkflow()` / `getWorkflowRun()`| associates one document execution with a workflow run | built on main |
960
997
|`Git.revParse()`| verifies and resolves one Git revision expression contextually | built on main |
961
998
| workflow run storage | creates or compatibly finds one run by public run ID, retains its identity, state, document executions and filtered journal, and validates immutable Workspace roots through one provider-owned connection entry | built on the #365 stack; public workflow execution is unbuilt |
0 commit comments