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 d701c9b
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
534
535
native Bash.
535
536
537
+
## Document targets
538
+
539
+
A root document addresses its own sections. The outline is discovered from the
540
+
document's static Markdown alone: only headings in the root flow are targets,
541
+
and a heading is addressable only when its text is statically rendered — a
542
+
heading generated inside a component, or one carrying an interpolation, has no
543
+
stable address, and neither does anything beneath it. Discovery therefore
544
+
parses a copy in which the scanner's top-level component spans are blanked,
545
+
because a Markdown parser reading raw XMD cannot tell a component's children
546
+
from the root flow.
547
+
548
+
Selection resolves exactly once, before the document expands and before any
549
+
authored effect runs. A selector may glob, but it must name exactly one catalog
550
+
entry: naming none and naming several are both failures, and two sections that
551
+
canonicalize to the same path stay two entries so the ambiguity is reported
552
+
rather than resolved arbitrarily.
553
+
554
+
The selector and the target it resolves to are different things, and only one
555
+
of them is identity. A selector is invocation input — it describes what a
556
+
caller asked for, and two callers may spell the same request differently. The
557
+
**exact resolved target** is what ran, so it is what a document execution
558
+
records durably, what a targeted workflow definition carries, and what a resumed
559
+
run is checked against. A caller's glob is never recorded and never re-resolved
560
+
against a newer checkout; a resumed run re-resolves the current selector against
561
+
the *recorded* content and refuses to continue unless it still names the
562
+
recorded target.
563
+
536
564
## Expansion identity
537
565
538
566
Core describes the executable element currently being expanded:
@@ -569,6 +597,14 @@ JavaScript object identity.
569
597
document execution receives expansion identity without installing workflow
570
598
middleware.
571
599
600
+
Selecting a document target does not disturb any of this. Projection retains
601
+
the original source ranges and scans each one under its own origin, so a
602
+
retained element keeps the offset and line it was authored at, and with them
603
+
its expansion ID. Two runs of the same document under different targets
604
+
therefore agree on the ID of every element they both retain, and may share IDs
605
+
without sharing effects — run identity and workflow-definition identity are
606
+
what tell those runs apart.
607
+
572
608
## Two layers
573
609
574
610
Error handling has two layers:
@@ -890,6 +926,7 @@ Status is measured against main.
890
926
|`<PrintErrors>` / `printErrors(fn)`| prints failures | built on main |
891
927
|`<Output>` region `output` mode | an undecided error fails the document execution | built on main |
892
928
|`Expansion` / `getExpansion()`| describes the current logical element expansion | built on main |
929
+
| 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 |
893
930
|`useWorkflow()` / `getWorkflowRun()`| associates one document execution with a workflow run | built on main |
894
931
|`Git.revParse()`| verifies and resolves one Git revision expression contextually | built on main |
895
932
| 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; Workspace effect publication is unbuilt |
0 commit comments