Skip to content

Commit f57ae74

Browse files
authored
✨ Address a root document's sections as targets (#421)
* ✨ Address a root document's sections as targets 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. * 🐛 Hold a resumed run to the selection its journal recorded A root import whose selector matched nothing failed the effect, so the journal kept only a serialized message and the replay guard delegated past every `err` result. A completed journal written by `Missing` then answered a later request for a section the document really has, with the old `Missing` error. A failed selection is an observation of the document, so it is recorded as one: its kind, the requested selector, the matches, and the catalog. The guard compares whole selection outcomes rather than target strings, reproduces a recorded failure from that record before the recorded Close can be reused, and reports any difference as stale input carrying no foreign object. `DocumentTargetError` now carries frozen, namespaced-tagged data and is recognized structurally, so inspection, a live run, and a replayed run all raise the same error with the same fields across separately loaded copies. A level is canonical only when decoding, label normalization, and canonical re-encoding reproduce it exactly, which refuses NFD, tabs, uncollapsed and edge whitespace, lowercase escapes, empty levels, raw operators, and a raw `#`. `formatDocumentReference()` only formats what `fileSource()` reads back. The recorded selector is sanitized invocation metadata: architecture.md now states that the exact canonical target is definition identity and a caller glob never substitutes for it. * 🔒 Fail closed on a recorded root selection this version cannot read "Not the root import" and "the root import, malformed" were one absent value, so a corrupted record fell through to the recorded terminal result and replayed an outcome the record no longer describes. The recorded root import is now a closed protocol: a repository selection with an optional exact canonical target, or a failed selection with an exact failure record. An unknown kind, a missing, unreadable, mistyped or extra member, and a noncanonical target are malformed, and malformed fails with one fixed cause-free diagnostic before the recorded Close can be reused — delegating nothing, executing nothing, appending nothing. The record carries the content it was taken from, so the selection is verified against that content rather than merely parsed: a recorded target must resolve to itself, and a recorded failure must be the failure that selector produces. `asDocumentTargetError()` returns a fresh local error built from reconstructed data instead of the candidate. An ordinary invocation failure has no fail-stop reason to preserve identity, and returning the candidate hands on whatever it owns — a list its owner can still rewrite, a revocable Proxy, a prototype with accessors. The data contract is closed to exactly five members with no symbol or non-enumerable extras, every list entry must be an exact canonical target, and the fields must describe an outcome selection could have reached. * 🔒 Make reading a recorded root selection total Reading a recognized successful root import could still throw: `matter()` rejects invalid frontmatter, a recorded property may be an accessor that refuses, and a record may come from a Proxy that will not enumerate. Each escaped carrying a parser message, a path, or whatever the record planted — from the one boundary whose job is to refuse. Reading is now total over journal-provided values. The record is parsed into this run's own copy before any member is read, the recorded content is parsed as part of reading the record for every shape, and every remaining throw becomes the same fixed cause-free diagnostic. The boundary is synchronous throughout, so it can swallow no cancellation and no durability failure. `isDocumentTargetError()` is documented as returning `boolean` rather than narrowing. A type predicate would claim the candidate is the safe value, which is exactly what it is not: the safe value is what `asDocumentTargetError()` reconstructs. DT58 changed failure data while keeping the derived message, so recognition failed on the message and the row proved nothing about list validation. The data-level rows now go at `parseDocumentTargetFailure()` directly. `.` and `..` are legal heading labels, so `../../etc/passwd` is a canonical heading path rather than filesystem authority; DT59 states that, and TX31 is renamed to say what actually refuses it — the catalog the recorded document derives. * 🔒 Tell an unreadable root result apart from an unrelated event Recognition and reading the settled value shared one `attempt()` whose absent answer meant "unrelated". A recorded root import whose `result.value` accessor refused was therefore not the root import at all: the guard delegated, and `durableRun` reused the recorded terminal result — so resuming with a section that really exists was answered with the failure of a request nobody made. Identification and reading are now separate, and absence and refusal are distinct answers. An event that will not say what it is stays unrelated. Once it is the root import, an absent, unreadable or invalid result or settlement is malformed, except the ordinary failed settlement, which selection knows nothing about; a successful result whose value is absent or unreadable is malformed too. The boundary begins where the durable protocol hands the event over. A `result` envelope that cannot be read at all fails inside `durableRun`'s own replay indexing, before any guard runs, so no diagnostic of this protocol applies there — TX40 states that and pins what still holds: the recorded terminal result is not reused, nothing authored runs, nothing is appended. * 🔒 Index a retained Yield's identity without reading its result `ReplayIndex` read every Yield's result while building itself, before any replay guard's check phase. A stream that would not produce one therefore failed inside construction and carried its own error out past every refusal — which is how an unreadable root-import envelope escaped the total, sanitized journal-reading contract as a raw accessor message. Indexing now reads identity, which is what indexing is for, and leaves the result alone until a consumer asks. A guard that would refuse an event gets its chance first, so an unreadable envelope reaches the existing malformed classification and the one fixed cause-free diagnostic. The read happens once and is kept, so a source that answers differently on a second read cannot change what replay already used. TX40 drops its exception and joins TX38, TX39 and TX41 under the full contract: the fixed diagnostic, no recorded terminal result reused, no planted text in message, stack, stringification, spreading or cause, nothing expanded and nothing appended, for the recorded selector and for a different valid one. The ordering property itself is pinned in the durable-streams suite. * 🔒 Let a guard and replay read one settled result, not two `ReplayIndex` memoized a result only for accesses through its own entry, while the check phase was still handed the stream's own events. A guard and the replay consumer therefore performed separate reads, and a source that answered differently between them decided one thing for validation and another for execution. Both answers can be entirely valid. Resuming a partial journal with target Alpha, an accessor returning a real Alpha selection and then a real Beta selection had the guard approve Alpha, the run execute Beta, and a successful Close published for a section nobody asked for — exact-target identity broken with nothing malformed anywhere. Each retained Yield now owns one cell for what it settled to, and the check phase is handed those retained Yields rather than the stream's events, so both phases observe one value and the stream is consulted at most once. The result is snapshotted as a frozen copy of its own members, so a settled `value` is read once rather than re-read per access, and a read that threw is remembered and re-raised rather than retried. The unit rows could not have caught this: they exercise the index alone. The new rows are a durableRun integration regression and a core regression built from two real recorded selections. * 🔒 Detach retained results, anchor the preamble, and require a root import Three architecture blockers. A retained result was stable only at the top: `{ ...result }` froze the outer object while `value` stayed the journal's own. A nested `target` accessor answering Alpha to the check phase and Beta to replay had an Alpha resume execute Beta. The whole result tree is now rebuilt from members read once each, so nothing the stream still owns remains reachable. The copy is not frozen through — detaching is the claim against the stream, and freezing would be one against the consumer: an eval binding restored from a journal is pushed to by the iteration that resumes on it, which LOOP49 pins. The preamble was anchored to the first outermost heading rather than the first root-flow heading, so a document opening at a deeper level than its title put an earlier addressable section inside the preamble — retained and executed by every other target while still being a target itself. A completed journal whose root import was missing reused its Close: the per-event check phase has nothing to object to in a journal that omits the event. Guards now receive the retained history once through a new `admit` phase, after every event has been offered and before terminal reuse, and an XMD replay refuses a terminal history that does not establish exactly one recognizable root import. WR13's hand-seeded journal gains the root import a real completed run always records; it still tests that a completed journal restores with no live run. * 🔒 Own definition identity in the journal, not in replaceable policy Six contracts from architecture review. Exact-target validation was installed through `ReplayGuard.around()`. Guards compose, and an enclosing handler may decline to call `next` — which is what composition is for, and why identity cannot live there. The execution now owns the journal it replays through: a private gate inside `readAll` reads the retained history once, validates the recorded selection and the required root-import structure against it, and hands the same snapshot onward. Public guard policy stays composable and can suppress other guards; it cannot suppress this. Partial histories are held to the same selection rule. A retained Yield now has one identity — event type, coroutine, and complete effect description — read together, detached, and kept, so the gate, the index, public policy, and replay cannot be shown different events. Settlement stays lazy and separate. Reusing a terminal result requires exactly one recognizable root import belonging to the terminal coroutine: reusing that result means standing behind the selection its import established. Detached results are ordinary mutable JSON. Detaching is a claim against the stream, not against the consumer; members stay writable and configurable, and `__proto__` remains an own data member. Target resolution now precedes schema compilation on every public path, so a caller who named a section the document does not offer hears that rather than a complaint about a schema they never reached. * 🔒 Retain every event the history decides with, not only its yields `retainEvents` read `event.type` to classify and `RetainedYield` read `source.type` again, and Close events were handed on as the backend's own objects. A Close could therefore belong to a child coroutine while admission asked and to the root while the index did: the gate saw no terminal result for `root` and admitted a history whose root import had been removed, and the run then returned the recorded output — Alpha's, for a request for Beta. The discriminator is now settled by the classification that chooses an event's retained kind and never read from the source again. Close events are retained too, with their coroutine settled once and their result detached and memoized. An event that refuses to say what it is is refused from every member, and a refusal is remembered rather than retried. A Yield's settlement stays lazy, so public guard check remains the first ordinary consumer. The gate refuses a history it cannot classify, and requires the root import whenever any completion was recorded: a Close means some coroutine of this execution finished, and every coroutine it has exists because the root document was imported. Retained events present their members as ordinary own properties, so they spread, serialize, and compare like the plain events they stand for. `detachJson` and the retained classes are internal again; only `retainEvents` stays public, because core owns its own journal gate across the package boundary. Their behavior is exercised from durable-streams' own tests. * 🔒 Settle a retained terminal result while the history is retained A retained Close detached its result only when the getter was first read. The execution-owned gate completed without touching it, so public ReplayGuard policy — code any enclosing scope may install — ran in the interval between admission and terminal reuse with the backend still owning the answer. Resuming an intact Alpha journal under a `check` handler that rewrote the raw Close result returned `"planted after admission"`, with nothing appended: a run admitted on one history and completed on another. A Close now settles both its coroutine and its result as the history is retained, before admission can complete, and admission recognizes the retained terminal result so a refusal becomes this run's fixed cause-free diagnostic rather than a failure surfacing later. Memoizing on first access closes repeated reads and leaves the window open, so it is not what this does. A Yield's settlement stays lazy, keeping public guard check its first ordinary consumer. * 🔒 Let policy observe the retained history without holding it Public ReplayGuard check, admit and decide received the authoritative retained events, so policy — code any enclosing scope may install — could rewrite what the private gate had already validated and what replay was about to consume. A partial Alpha journal resumed as Alpha, with check rewriting the retained root-import target to Beta, executed the Beta projection. A retained effect named A, renamed to B by check, let a workflow asking for B consume A's result without B ever running. One history now has three views. The authoritative retained graph is what admission validated and replay consumes, detached from the backend and frozen through so nothing that receives it can rewrite a later decision. Guards receive an isolated deep mutable copy per invocation, so middleware composes as freely as before and nothing it writes flows back. What workflow code receives is a fresh mutable copy taken from the authority at consumption, so a resumed binding stays ordinary JSON its own continuation writes to. * 🔒 Apply the authority boundary to every Result path Two paths were missed. `durableRun` returned a completed Close's value straight from the frozen authority, so a caller of a finished run received a frozen object where a live run had given ordinary JSON and mutation threw. And a successful settlement carrying no value was left writable, so a caller of a public `ReplayIndex` observation could add one before replay read it. Every retained settlement is now frozen through — a success with a value, a `Result<void>` with none, a failure, and a cancellation, on Yield and Close alike — and a completed run hands back a fresh consumer copy exactly as a replayed effect does. Mutating what one completed replay returned cannot reach the authority or the next replay, and completed replay still runs nothing and appends nothing. The specification and README now say plainly that "mutable replayed value" means the fresh consumer copy, and that the retained Result is frozen through. * 🔒 Carry the journal witness across the admission wrapper Journal provenance is not transitive: a wrapper is unproven unless its wrapping site carries the source's witness onto it. Core puts two wrappers on the journal a host supplies — the secret filter, which preserves explicitly, and the execution-owned target-admission gate, which did not. A live coordinator therefore received no provenance, and a Workspace provider refused the operation before any transaction. The gate is a trusted wrapping site: core installs it before any document code exists and it delegates every append to the exact stream it was handed. It now transfers the witness that exact source already has, and nothing more — it establishes none, so an unproven journal stays unproven, a generic guard or a custom wrapper gains nothing, and a separately loaded copy cannot transfer the canonical witness. The workflow specification, architecture.md, the durable-stream README and the executable-MDX prose named the secret filter as the one trusted site; the admission wrapper is now named as the second. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 443a591 commit f57ae74

24 files changed

Lines changed: 7541 additions & 89 deletions

‎architecture.md‎

Lines changed: 92 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,14 @@ Existing documents and code get aligned to this section retroactively.
2424
| middleware | applied by the lexical structure, used by runtime execution |
2525
| workflow run | a workflow being carried out with its progress and outcome recorded durably; document executions perform its work, while ongoing effects remain scoped to the document execution in which they run |
2626
| document execution | one evaluation of a root document initiated through `execute()`, producing one output stream and one completion result while reading and appending a durable journal; its ongoing effects belong to the Effection scope in which the evaluation runs |
27-
| workflow definition | what a workflow run is a run of: a versioned descriptor naming an immutable object — its format and object ID — together with the repository-relative path of the root document inside it. A repository locator is not part of it, and it is distinct from every Repository created inside the run's Workspace |
27+
| workflow definition | what a workflow run is a run of: a versioned descriptor naming an immutable object — its format and object ID — together with the repository-relative path of the root document inside it, and the exact canonical document target when one is selected. A repository locator is not part of it, and it is distinct from every Repository created inside the run's Workspace |
2828
| retrieval metadata | replaceable, credential-free information about where a workflow definition can be fetched from now; it takes no part in run identity and is reauthorized by the host before use |
2929
| stop reason | why a workflow run or a document execution stopped: a categorical host code, or a reference to an already-filtered journal event |
3030
| run ID | an opaque stable public identifier generated by the host or selected by an authorized caller; it associates the run's durable records and effects, remains unchanged for the life of the run, and has no semantics beyond equality and lifecycle addressing |
3131
| definition base | the Git revision supplied to choose a workflow definition's pinned commit |
3232
| Repository base | the optional Git revision from which one named Workspace Repository initializes its primary checkout |
3333
| 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 |
3435
| expansion | one logical evaluation of an authored executable element within a document execution |
3536
| 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 |
3637
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
@@ -603,6 +604,81 @@ interpreter; graceful Worker shutdown alone is insufficient. Worker Shell
603604
exposes no native executable or host PATH and is not described as POSIX or
604605
native Bash.
605606

607+
## Document targets
608+
609+
A root document addresses its own sections. The outline is discovered from the
610+
document's static Markdown alone: only headings in the root flow are targets,
611+
and a heading is addressable only when its text is statically rendered — a
612+
heading generated inside a component, or one carrying an interpolation, has no
613+
stable address, and neither does anything beneath it. Discovery therefore
614+
parses a copy in which the scanner's top-level component spans are blanked,
615+
because a Markdown parser reading raw XMD cannot tell a component's children
616+
from the root flow.
617+
618+
A document's preamble is what precedes its outline — the source before the first
619+
root-flow heading, whatever its depth. A document may open at a deeper level than
620+
the one supplying its title, and an earlier section is a target in its own right
621+
rather than preamble every other target carries.
622+
623+
Selection resolves exactly once, before the document expands and before any
624+
authored effect runs. A selector may glob, but it must name exactly one catalog
625+
entry: naming none and naming several are both failures, and two sections that
626+
canonicalize to the same path stay two entries so the ambiguity is reported
627+
rather than resolved arbitrarily.
628+
629+
The selector and the target it resolves to are different things, and only one of
630+
them is identity.
631+
632+
**The exact canonical target is definition identity.** It is what ran, so it is
633+
what a document execution records durably, what a targeted workflow definition
634+
carries, and what a resumed run is checked against.
635+
636+
**A caller's glob is non-authoritative invocation metadata.** It describes what
637+
a caller asked for — two callers may spell one request differently — and it
638+
never substitutes for the exact target: it does not occupy the recorded
639+
exact-target field, it never enters a workflow definition, and it is never
640+
re-resolved against a newer checkout to decide what a resumed run means. A glob
641+
is retained in exactly one place, a failed selection's structural record, and
642+
only so that an ordinary failed execution can be reproduced.
643+
644+
A resumed run re-resolves the current selector against the *recorded* content
645+
and refuses to continue unless the outcome is the one recorded. A failed
646+
selection is an outcome too, and is recorded and compared as one — otherwise a
647+
journal left by a selector that matched nothing would answer a later request for
648+
a section that does exist.
649+
650+
Validating that identity is **execution-owned**. Replay guards are composable
651+
policy — a handler installed further out may decline to delegate — so identity,
652+
which must not be negotiable, is not decided there. The execution owns the
653+
journal it replays through and validates the recorded selection inside the read
654+
itself, ahead of public guard policy, of a retained terminal result being
655+
reused, of authored work, and of any append. The retained history it owns covers
656+
every event that takes part in that decision, a recorded completion included, so
657+
no event can present one identity to the validation and another to the run.
658+
659+
Three views of that history stay distinct. The **authoritative** one is what
660+
admission validated and replay consumes, and it is immutable to policy.
661+
Replaceable public policy reads an **isolated observation** of it, so a handler
662+
composes freely without acquiring the authority the gate exists to withhold.
663+
What a document receives is a **fresh mutable copy**, because a resumed binding
664+
is ordinary data its own continuation writes to. Reusing a terminal result also
665+
requires exactly one recognizable root import belonging to the coroutine whose
666+
result is being reused.
667+
668+
Every public path validates in one order: parse the source, resolve the target,
669+
compile schemas, then build the projected definition. A caller who named a
670+
section the document does not offer hears that, rather than a complaint about a
671+
schema they never reached.
672+
673+
A recorded selection is a closed protocol, and a record that does not satisfy it
674+
is refused rather than delegated. "This event is not the root import" and "the
675+
root import, malformed" are different answers: one continues, the other fails
676+
before the recorded terminal result can be reused, without executing authored
677+
work or appending history. The record carries the content it was taken from, so
678+
the selection is verified against that content rather than merely parsed, and
679+
reading it is total — every way journal-controlled data can refuse to be read is
680+
the same refusal, carrying nothing the record supplied.
681+
606682
## Expansion identity
607683

608684
Core describes the executable element currently being expanded:
@@ -639,6 +715,14 @@ JavaScript object identity.
639715
document execution receives expansion identity without installing workflow
640716
middleware.
641717

718+
Selecting a document target does not disturb any of this. Projection retains
719+
the original source ranges and scans each one under its own origin, so a
720+
retained element keeps the offset and line it was authored at, and with them
721+
its expansion ID. Two runs of the same document under different targets
722+
therefore agree on the ID of every element they both retain, and may share IDs
723+
without sharing effects — run identity and workflow-definition identity are
724+
what tell those runs apart.
725+
642726
## Two layers
643727

644728
Error handling has two layers:
@@ -935,7 +1019,12 @@ It qualifies only while every one of these holds:
9351019
it;
9361020
- establishment and transfer occur only through the canonical module's
9371021
`establishJournalProvenance()` and `preserveJournalProvenance()`, one fresh
938-
witness per stream, with duplicate establishment refused; and
1022+
witness per stream, with duplicate establishment refused;
1023+
- transfer happens only at a trusted wrapping site — one installed before any
1024+
code the journal's content could influence, delegating to the exact stream it
1025+
was handed. A document execution's journal passes through two: the secret
1026+
filter and the execution-owned target-admission wrapper. Each transfers only
1027+
what its source already had, so an unproven journal stays unproven; and
9391028
- it retains no execution, lifecycle, journal content or provider state.
9401029

9411030
The exception exists because the exact-object, anti-forgery and loaded-copy
@@ -992,6 +1081,7 @@ Status is measured against main.
9921081
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
9931082
| `<Output>` region `output` mode | an undecided error fails the document execution | built on main |
9941083
| `Expansion` / `getExpansion()` | describes the current logical element expansion | built on main |
1084+
| 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 |
9951085
| `useWorkflow()` / `getWorkflowRun()` | associates one document execution with a workflow run | built on main |
9961086
| `Git.revParse()` | verifies and resolves one Git revision expression contextually | built on main |
9971087
| 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 |

‎packages/core/mod.ts‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,25 @@ export type {
130130
ExecutionApi,
131131
DocumentExecution,
132132
} from "./src/execute.ts";
133-
export { INLINE_SOURCE_PATH, inlineSource, rootSourcePath } from "./src/root-source.ts";
134-
export type { InlineRootDocument, RootDocumentSource } from "./src/root-source.ts";
133+
export {
134+
fileSource,
135+
formatDocumentReference,
136+
INLINE_SOURCE_PATH,
137+
inlineSource,
138+
rootSourcePath,
139+
} from "./src/root-source.ts";
140+
export type {
141+
FileRootDocument,
142+
InlineRootDocument,
143+
RootDocumentSource,
144+
} from "./src/root-source.ts";
145+
export {
146+
asDocumentTargetError,
147+
DocumentTargetError,
148+
isDocumentTargetError,
149+
parseDocumentTargetFailure,
150+
} from "./src/document-targets.ts";
151+
export type { DocumentTargetErrorKind, DocumentTargetFailure } from "./src/document-targets.ts";
135152
export { inspectComponent, inspectDocument } from "./src/inspect.ts";
136153
export type {
137154
ComponentInfo,

0 commit comments

Comments
 (0)