✨ One place for a run's setup, and a Syntax description anything may compose

[taras]

U3 of the upstream-repository prerequisite stack. Stacked on landed U2
(#906); based on main.

Why

Two problems with one shape: something a run needs has no place to be
established, so it gets established somewhere that is not the run.

A command host had no seam for its own live dependencies. A Files provider, a
recorder or a service had to be arranged outside the execution and reach in,
which is why two REPL entries could not each own their own state, and why an
isolated host="run" child inherited whatever a parent happened to install.

And a <Syntax /> description travelled by value on the private expansion
environment. One execution accepted exactly one ExecutionInstallation.symbols
provider, two were refused rather than ordered, and nothing could narrow,
transform or extend what a document was shown. xmd plan needed a different
profile than the execution writing the Plan, so it got a bespoke installation
member instead of composition.

What changes

Before:

• A host arranged its live dependencies outside the execution and reached in.
• ExecutionInstallation.symbols carried one descriptive provider per
  execution; two were refused. The description was a value on core's private
  environment, and no middleware could reach it.

After:

• Execution.init(): Operation<void> runs once in the scope the invocation
  already owns. A host installs its live dependencies there and delegates.
• Syntax is a contextual Api anyone may compose on. A host states its own
  profile with useSyntax(source); the execution's derived description is the
  fallback behind it; a trusted evaluation boundary narrows symbols for the
  subtree it evaluates. ExecutionInstallation.symbols and its count rule are
  gone.
• A description now registers, resolves and authorizes nothing. It may name a
  component this host will refuse, or hide one it will run; preflight decides
  either way.

How it works

runInvocation() → invoke(): copy trusted contributions, arm revocation
  → Execution.operations.init()        ← host installs live dependencies here
  → installation callbacks → documentation capture → Execution.execute policy

<Syntax /> → protected body (authenticated, site+form checked)
  → durable live callback → Syntax.operations.text | .documentation(names)
      → host middleware (useSyntax, at min) | narrowed admission
      → default → the execution's derived reference
  → retain the final answer → replay returns it without any live lookup

init is placed after the trusted copies and armed revocation, so nothing a
host installs can reach back and change what is already authoritative, and
before the installation callbacks and documentation capture, so what it
establishes is there for both. Its public default is no-op rather than a
refusal: an execution with no host middleware has no live dependencies to
establish and invents none.

The two ways a description gets supplied are deliberately different slots.
useRootSyntaxReference binds the execution's own reference as the value the
default reads — a default is furthest from the caller, so an enclosing
useSyntax() profile still wins. useNarrowedSyntax installs real middleware
at min for a boundary that admitted less than its enclosing site; that one is
meant to shadow, and it ends with the scope that installed it.

Review guide

Start with: packages/core/src/syntax-api.ts

Then review:

1. ExecutionApi.init and the Execution descriptor — packages/core/src/execute.ts
2. The init dispatch in invoke(), and the derived reference bound as the
   fallback in executeDocument()
3. packages/core/src/use-syntax.ts, and referencing() in
   packages/core/src/syntax-reference.ts — the one-basis-per-occurrence rule
4. packages/core/src/components/Syntax.ts — the dispatch moved inside the
   durable live callback
5. packages/cli/src/syntax.ts useCommandSyntax, and the Plan path
   (cli.ts, plan.ts, plan-writer-profile.ts)

Look carefully at:

• syntax-reference.ts documentation(): it resolves the authoring basis,
  publishes it on a scoped context, then reads effective symbols through the
  Api. That re-entry is what lets a host or boundary decide the availability
  annotation, and the scoped basis is what stops one occurrence inspecting a
  moving root twice. Two occurrences enter two scopes and resolve independently.
• The min slot in use-syntax.ts and useNarrowedSyntax. Getting these
  backwards means a host profile is shadowed by core's own fallback.
• expand.ts narrowedSyntax: set only where a boundary replaced the
  reference. The ordinary handle leaves it absent on purpose.
• Failure and cancellation during init (EI4/EI5) — settlement must wait for
  acquired teardown, and reach no policy, no root import and no body.

What must stay true

• <Syntax>'s name, selected definition and invocation identity are
  canonical core's, however freely the description is customized — enforced by
  the protected tier and issued-invocation checks, checked by
  syntax-loaded-copy, evaluate-loaded-copy and SA9.
• A description confers no execution authority — enforced by keeping admission
  in selectComponent()/preflight, checked by SA6 (a described-but-forbidden
  name is still refused) and SA7 (a hidden admitted component still runs).
• Completed <Syntax> replay consults no live provider — enforced by querying
  the Api only inside the durable live callback, checked by SA5, which installs
  symbols, text, catalog and source providers that throw if reached and
  replays both a complete and a partial history.
• init cannot alter what was already captured — enforced by its position
  after the trusted copies, checked by EI3.
• One execution's initialized state is its own — enforced by using the existing
  invocation scope, checked by EI6 (concurrent), EI-REPL (two entries under one
  session attachment) and EI-child (isolated child reassembles, inherits no
  parent handler).
• One named occurrence resolves one authoring basis and one effective symbols
  answer — enforced by the scoped basis in referencing(), checked by SA2's
  source === 1 && effective === 1 and SA4's two moving occurrences.
• Only core's own unknown-name selection becomes the safe retained refusal;
  provider failures stay terminal — checked by SA8, including a
  provider-thrown UnknownComponentError.

How to verify it

Tier EI (packages/core/tests/execution-init.test.ts) and tier SA
(packages/core/tests/syntax-api.test.ts) are new. Both are written to fail on
a plausible wrong implementation rather than to confirm the right one:

• EI2 asserts the exact order init, install, documentation, execute, document
  and fails if init is moved into execute middleware after capture.
• EI4/EI5 hold a cleanup open and assert the invocation has not settled and
  the stream is empty; they fail if settlement merely signals cancellation
  without joining teardown.
• EI7 proves a no-op initializer supplies no Files provider and an explicit one
  does, and that the provider is gone again outside the scope.
• SA1 reads .text twice over a file that changes in between and asserts two
  distinct answers — it fails if a default is a stored consumable generator.
• SA3 asserts a synthetic answer leaves the source read count at 0; it fails
  if a non-delegating provider still triggers default inspection.
• SA5 fails if replay performs any live lookup.
• SA9 builds a second, independent createApi descriptor with the same name and
  shows its middleware answers the protected component — the composition is
  intentional, and harmless because descriptions grant nothing.

deno task test packages/core/tests/execution-init.test.ts packages/core/tests/syntax-api.test.ts

Results at this revision are in Risks below.

Scope

Included

• Execution.init, exported with the descriptor and request types from
  @executablemd/core/api.
• Syntax/SyntaxApi with Operation-valued symbols and text and an
  Operation-valued documentation(names), from /api and the package root.
• useSyntax(source) from @executablemd/core/host.
• Removal of ExecutionInstallation.symbols, its provider-count refusal, its
  argument through executeDocument()/rootSyntaxReference(), and the
  SyntaxSymbolsProvider alias.
• Migration of xmd plan, xmd syntax, the REPL and the Plan fixtures.
• Architecture, executable-mdx-spec §5.3.1 and §§8–9, plan-command-spec,
  and new spec tiers EI and SA.

Intentionally unchanged

• U4's metadata/identity work and U5's generated-selection and input removal.
• Durable preparation's position: still journaled work after retained-history
  validation, not ordinary initialization.
• Plan's structural validation and trusted Files/Permissions reads; its retired
  read grants and Scope observer stay removed.
• REPL's agent.owning(key) attachment, lifecycle installation and per-entry
  journal lifetimes. init adds state below that owner.
• Every other ExecutionInstallation member. No blanket migration.
• Deno/Node/Bun/compiled startup and provider absence.

New abstractions

• SyntaxApi + the Syntax descriptor exist because three consumers already
  asked the same three questions in three places: the protected component,
  xmd syntax, and a Plan's authorship. Accepted as architecture amendment A2.
• useSyntax(source) exists because a host has a lazily-inspectable profile
  and documentation contributions that only exist in its assembly scope;
  binding one without the other is what sent named metadata to the wrong
  catalog. Accepted as A3, and it is the only public setup helper added.
• useNarrowedSyntax / useRootSyntaxReference are local to core and exist to
  keep the shadowing slot and the fallback slot from being confused.
• PlanDependencies.installSyntax / PlanWriterProfile.installSyntax are
  private to the CLI and replace the removed symbols member one-for-one.
• Each new abstraction has multiple concrete uses or a clear justification.
• No speculative functionality is included.

New dependencies

None. A2 uses the installed @effectionx/context-api 0.6.0 contract with no
adapter, cast or runtime hook. No lockfile or manifest change.

Generated or mechanical changes

• packages/core/src/syntax-markdown.ts / documentation-index.ts /
  mod.ts: NO_DOCUMENTATION moves to the renderer that emits it, keeping its
  package-root export. Not cosmetic — it cuts a real module cycle. Reverting it
  fails evaluation-profile.test.ts with ReferenceError: Cannot access 'SYNTAX_PROTECTED' before initialization, because
  components/Syntax.ts → syntax-api.ts → syntax-markdown.ts → documentation-index.ts → components/registration.ts → components/protected.ts
  closes a cycle through protected.ts's own module body.
• packages/core/tests/syntax-component.test.ts: ~14 call sites wrap direct
  reference.documentation(...) reads in a helper that installs the reference
  first. Required, not stylistic — availability is now read through the Api, so
  the reference is no longer usable standalone. No assertion changed.
• packages/core/tests/protected-content.test.ts and the stating(...)
  fixtures in syntax-component.test.ts / evaluate-component.test.ts follow
  the SyntaxReference.symbols() return type and the removed installation
  member. No assertion changed.
• packages/cli/src/plan-writer-profile.ts is mostly re-indentation: the body
  moves into a nested scoped(). The descriptive setup enters the target run's
  declarative bootstraps, which re-register names the operational install above
  already holds, and registration refuses two registrations for "AgentProvider" at the same scope unless the shadowing one nests.

Risks and limitations

• A separately loaded copy can answer for the description. SA9 demonstrates
  it. This follows from name-based contextual dispatch and is accepted: a
  description grants nothing, and the protected definition, routing and
  admission are unaffected. Reviewers who disagree should say so — it is a
  property of the accepted A2 boundary, not an implementation accident.
• site.syntax remains a presence gate in the protected body even though
  the answer now comes from the Api. Kept deliberately as the site validation
  the contract preserves, so an expansion driven outside an execution refuses
  while naming the element. It is reachable only in that case.
• Recorded answers are compatible; SyntaxSymbols version and schema are
  unchanged, and completed replay returns retained text.
• Rollback is a revert of this single commit. No persistence format, dependency
  or lockfile changes, so nothing migrates back.

Evidence at this revision

Base a0320347. Every command below was re-run after rebasing onto it, and
after deno task setup (the rebase brought #908's package.json lint script
change, which the build preflight refuses to build against — no dependency or
lock delta, and setup left both clean).

Check	Result
core group — execution-init, execution-protocol, files-fatal, workflow-component-bundle	7 passed / 112 steps / 0 failed
Syntax group — 8 core suites incl. syntax-api, syntax-component, *-loaded-copy, evaluation-profile, generated-xmd	59 passed / 417 steps / 0 failed
CLI group — 8 suites incl. testing-execution-host, repl-execution, syntax-cli, plan-command-document, plugin-host	41 passed / 226 steps / 0 failed
Workflow — workflow-run, workflow-run-journal	10 passed / 69 steps / 0 failed
Plan-affected — plan-cli, plan, plan-host-acts, agent-adapters	5 passed / 53 steps / 0 failed
Node (tsx --test)	134 passed / 0 failed
Bun	134 passed / 0 failed
pnpm run lint (oxlint, prose oxlint, lint-architecture, oxfmt --check, knip)	exit 0, no errors
scripts/tests/oxlint-policy.test.ts (#908's banned-word regressions)	2 passed / 20 steps / 0 failed
deno task build	exit 0
compiled — plan-component-compiled, plugin-compiled	6 passed / 15 steps / 0 failed
deno check --frozen over the four entrypoints	exit 0

The compiled evidence was re-run against a binary rebuilt at this revision, not
the pre-rebase one.

Planner and Architect both returned PASS at ac466780, the pre-rebase revision
with identical behavior; the rebase resolved three prose-only conflicts from
#908 (claim→register in architecture, two reworded header hunks in
components/Syntax.ts where the landed vocabulary was adopted, and the
ExecutionInstallation.symbols doc this PR deletes). No code conflicted.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• Generated or mechanical changes are clearly identified.
• The description matches the final diff and test results.

[taras]

Reviewed d42287abe0241e85732617fe29f79b21d31c6b56 against the accepted #913 documentation (e3afc34, merged as a1621d3). The architectural direction is consistent: initialization belongs to the existing execution owner; Syntax descriptions compose normally; component selection, admission and retained publication keep their owners. I found documentation corrections and readability work before calling the prose aligned with #913. These are non-blocking observations for the existing architectural implementation verdict.

1. Finish separating descriptions from execution permission. In the Syntax specification, “At a root the two are one set of symbols and everything selected is available” is no longer generally true: SA2 filters Hidden from effective symbols while named lookup still documents it as unavailable, without an evaluation boundary. Likewise, SyntaxApi's member comments promise “what may be written” and “the same answer as Markdown,” although SA6/SA7 separate descriptions from admission and SA2 permits text-only replacement. Qualify the root statement as the uncustomized default. Describe symbols as the effective structured description and text as the effective text whose default renders those symbols. In SyntaxReference, replace “customized what may run” with “customized the descriptive view.” Keep the existing availability label and admission behavior.

2. Remove the remaining host-only/private-description story. The new catalog paragraph calls replacement “a composition the host assembled, not a read a document answered.” The public same-name API is deliberately composable by ordinary middleware; SA9 demonstrates another descriptor supplying the protected component's text. Distinguish the captured package asset/catalog from the effective answer: canonical collection owns the former, while live Syntax middleware can replace the latter. SyntaxReference's Context rationale also carries the old concern about a document answering its vocabulary; that concern no longer explains this descriptive boundary. State explicitly that protection keeps component selection, invocation and durable recording canonical while the returned description is customizable.

3. Keep the detailed contract in one owning chapter. The new architecture Syntax block, language-spec API block and module headers repeat the same fallback/provider ordering, lazy defaults, per-occurrence basis and scope-restoration explanation. Follow 📝 Make the architecture documents easier to read and navigate #913's split: Capability-backed execution and the syntax symbols boundary own those invariants; the feature spec keeps signatures, representative usage, observable behavior and EI/SA conformance, with deep links to those owners. Keep source comments for the surprising constraints: reusable Operation defaults, fallback versus min precedence, one basis per lookup, teardown ordering and the renderer/index cycle. Trim repeated introductions and delivery history such as “before this” and “stay what they were.”

4. Make the remaining API comments self-contained and consistent. ExecutionApi's interface-level introduction describes every handler as receiving an ExecutionRequest, but init() receives none and document() receives a DocumentRequest; scope that explanation to execute. The new api.ts export comment calls Syntax a consumer boundary, while mod.ts says it is not a consumer-boundary concern. Document the boundary once at its owner; re-exports can simply identify the same descriptor and the supported import path.

Integration check: a scratch three-way merge with #913 applies cleanly. All existing anchors in the three affected documents survive, and #913's README reading routes and AGENTS guidance remain unchanged. Preserve that result when integrating the branch. The evidence above is a source/spec trace through SA2/SA6–SA9 and the initialization lifecycle; this comment does not reopen the accepted A2/A3 API decisions or the previous implementation verdict.

[taras]

PASS — documentation alignment with #913 on bc2c59c8b6f7a5854dda7b6a8bc70970003987ba (tree 3c4f45ca509e0de6ee820341c602319c7482386d). All four findings in my earlier comment are closed.

• Descriptions, reported availability and admission are now distinguished consistently, including the customized-root and text-only cases.
• The captured catalog and the customizable live answer have separate owners; the old host-only/private-description rationale is removed.
• The feature spec retains interfaces, usage and observable behavior and links to the architecture owners for the detailed invariants. The relative anchors are appropriate and resolve.
• Execution member comments describe their actual inputs, and the Syntax re-exports identify the same descriptor without conflicting boundary explanations.

I reviewed the complete eight-file delta. The five changed production TypeScript files have identical parsed code with comments removed; the executable change is confined to the ESM test fixture. A scratch three-way merge with the accepted #913 tree applies cleanly, preserves every existing anchor in the three affected documents, and leaves its README reading routes and AGENTS guidance unchanged.

No further changes are requested by this documentation review. A2/A3 remain settled. Keeping both commits preserves the reviewed revision and makes the correction traceable; no squash or force-push is needed for this review.