Repository navigation
Commit f57ae74
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
File tree
- packages
- core
- src
- tests
- durable-streams
- specs
- tests
- workflow/tests
- specs
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
27 | | - | |
| 27 | + | |
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
| 34 | + | |
34 | 35 | | |
35 | 36 | | |
36 | 37 | | |
| |||
603 | 604 | | |
604 | 605 | | |
605 | 606 | | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
| 630 | + | |
| 631 | + | |
| 632 | + | |
| 633 | + | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
| 647 | + | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
| 653 | + | |
| 654 | + | |
| 655 | + | |
| 656 | + | |
| 657 | + | |
| 658 | + | |
| 659 | + | |
| 660 | + | |
| 661 | + | |
| 662 | + | |
| 663 | + | |
| 664 | + | |
| 665 | + | |
| 666 | + | |
| 667 | + | |
| 668 | + | |
| 669 | + | |
| 670 | + | |
| 671 | + | |
| 672 | + | |
| 673 | + | |
| 674 | + | |
| 675 | + | |
| 676 | + | |
| 677 | + | |
| 678 | + | |
| 679 | + | |
| 680 | + | |
| 681 | + | |
606 | 682 | | |
607 | 683 | | |
608 | 684 | | |
| |||
639 | 715 | | |
640 | 716 | | |
641 | 717 | | |
| 718 | + | |
| 719 | + | |
| 720 | + | |
| 721 | + | |
| 722 | + | |
| 723 | + | |
| 724 | + | |
| 725 | + | |
642 | 726 | | |
643 | 727 | | |
644 | 728 | | |
| |||
935 | 1019 | | |
936 | 1020 | | |
937 | 1021 | | |
938 | | - | |
| 1022 | + | |
| 1023 | + | |
| 1024 | + | |
| 1025 | + | |
| 1026 | + | |
| 1027 | + | |
939 | 1028 | | |
940 | 1029 | | |
941 | 1030 | | |
| |||
992 | 1081 | | |
993 | 1082 | | |
994 | 1083 | | |
| 1084 | + | |
995 | 1085 | | |
996 | 1086 | | |
997 | 1087 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
130 | 130 | | |
131 | 131 | | |
132 | 132 | | |
133 | | - | |
134 | | - | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
135 | 152 | | |
136 | 153 | | |
137 | 154 | | |
| |||
0 commit comments