Story
As a host consuming an executable document, I want expansion to return output
that carries everything needed to consume it, so presentation does not depend on
a separate execution-private record.
Example
One expansion can produce reader-facing prose around generated XMD source:
Here is the generated workflow:
<Plan.Step>...</Plan.Step>
Run it after reviewing the source.
A terminal consumer may format the surrounding prose while preserving the
generated XMD. A file or programmatic consumer may retain the output without
terminal presentation. Each consumer makes that decision from the expansion
output it receives; it does not also receive a hidden set of segment identities.
Current gap
Today an installed Markdown component can be admitted with exact: true.
Canonical expansion then records the resulting text segments in an
ExactSource weak set carried by ExecutionEnvironment. Rendering consults
that separate record, groups adjacent segments, and passes an exact boolean
to DocumentOutput so presentation middleware knows which writes to leave
untouched.
That preserves source bytes, but it splits the meaning of output between the
output itself and execution-private state. The term “exact” also obscures the
actual distinction: source intended for another program versus prose intended
for presentation.
Contract
Keep expanded output self-contained until it reaches a consumer. Any distinction
needed to consume mixed prose and source travels with the output itself rather
than through an ExecutionEnvironment side record.
The consumer owns the presentation decision. A terminal presentation can format
prose and preserve source syntax and whitespace; another consumer can choose a
different presentation or retain the unpresented output. Expansion does not
write to a default destination or choose terminal behavior.
Preserve the current provenance boundary. An ordinary imported component,
middleware answer, authored segment, or object field cannot make its bytes
bypass presentation by claiming to be source. If mixed output still requires a
source/prose classification, canonical expansion supplies that classification
in the returned output.
Replace “exact” terminology on the affected supported interfaces with names
that describe source, prose, or presentation directly. Record any public
compatibility impact through the repository's release process.
Acceptance
- An expansion result can be handed to a consumer without also handing it an
ExactSource record or the ExecutionEnvironment that produced it.
- One result can contain prose before and after generated source. Terminal
presentation formats only the prose and preserves the source's significant
whitespace and Markdown syntax.
- A non-presenting consumer can consume the same result without terminal
formatting.
- An open import or middleware-provided component cannot obtain the
source-preserving path by adding a field or constructing an output object.
ExecutionEnvironment no longer owns an exact-source or presentation
record.
- Maintained architecture, specifications, exported types, and JSDoc describe
the resulting output and consumption boundary consistently.
Evidence
Focused regressions cover mixed prose/source output under both presenting and
non-presenting consumers. Existing exact-source and whitespace-normalization
controls remain discriminating during the migration, including the negative
case where import middleware claims source treatment.
Run the affected core tests selected from the changed boundary, including
packages/core/tests/declared-markdown-component.test.ts and
packages/core/tests/output-normalize.test.ts.
Dependency
Start this work after #806 lands. It is a follow-up discovered while reviewing
ExecutionEnvironment; it does not expand the active #806 implementation.
Out of scope
- Changing which installed components are permitted to produce source.
- Changing structural expansion, component resolution, or journal semantics
unrelated to representing and consuming output.
Story
As a host consuming an executable document, I want expansion to return output
that carries everything needed to consume it, so presentation does not depend on
a separate execution-private record.
Example
One expansion can produce reader-facing prose around generated XMD source:
A terminal consumer may format the surrounding prose while preserving the
generated XMD. A file or programmatic consumer may retain the output without
terminal presentation. Each consumer makes that decision from the expansion
output it receives; it does not also receive a hidden set of segment identities.
Current gap
Today an installed Markdown component can be admitted with
exact: true.Canonical expansion then records the resulting text segments in an
ExactSourceweak set carried byExecutionEnvironment. Rendering consultsthat separate record, groups adjacent segments, and passes an
exactbooleanto
DocumentOutputso presentation middleware knows which writes to leaveuntouched.
That preserves source bytes, but it splits the meaning of output between the
output itself and execution-private state. The term “exact” also obscures the
actual distinction: source intended for another program versus prose intended
for presentation.
Contract
Keep expanded output self-contained until it reaches a consumer. Any distinction
needed to consume mixed prose and source travels with the output itself rather
than through an
ExecutionEnvironmentside record.The consumer owns the presentation decision. A terminal presentation can format
prose and preserve source syntax and whitespace; another consumer can choose a
different presentation or retain the unpresented output. Expansion does not
write to a default destination or choose terminal behavior.
Preserve the current provenance boundary. An ordinary imported component,
middleware answer, authored segment, or object field cannot make its bytes
bypass presentation by claiming to be source. If mixed output still requires a
source/prose classification, canonical expansion supplies that classification
in the returned output.
Replace “exact” terminology on the affected supported interfaces with names
that describe source, prose, or presentation directly. Record any public
compatibility impact through the repository's release process.
Acceptance
ExactSourcerecord or theExecutionEnvironmentthat produced it.presentation formats only the prose and preserves the source's significant
whitespace and Markdown syntax.
formatting.
source-preserving path by adding a field or constructing an output object.
ExecutionEnvironmentno longer owns an exact-source or presentationrecord.
the resulting output and consumption boundary consistently.
Evidence
Focused regressions cover mixed prose/source output under both presenting and
non-presenting consumers. Existing exact-source and whitespace-normalization
controls remain discriminating during the migration, including the negative
case where import middleware claims source treatment.
Run the affected core tests selected from the changed boundary, including
packages/core/tests/declared-markdown-component.test.tsandpackages/core/tests/output-normalize.test.ts.Dependency
Start this work after #806 lands. It is a follow-up discovered while reviewing
ExecutionEnvironment; it does not expand the active #806 implementation.Out of scope
unrelated to representing and consuming output.