Skip to content

Defer executable document presentation until output consumption #814

Description

@taras

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions