You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit b66a4af
Browse filesBrowse the repository at this point in the historyBrowse files
✨ Install trusted Plugins before a document runs (#818)
XMD gains one generic, trusted Plugin boundary. A distribution supplies an
ordered list of bundled Plugins and an operator appends package or filesystem
Plugins with a repeatable `--plugin`. The complete list is loaded, admitted and
installed before anything imports a root document.
A Plugin is a plain structural value carrying a name and one optional
`install(request)`. What it returns crosses at the boundary a trusted host
already had — declared Markdown, structural syntax and its handler, journal
admissions — and it composes a run through three stable, namespaced contextual
APIs published from `@executablemd/core/api`: `Document`, `RootMetadata` and
`ActivePlugins`. `@executablemd/runtime/api` publishes the existing `Config` Api
a Plugin reads timeouts and verbosity through. Both root exports are unchanged.
`Document`'s terminal answers with `<Document />`. Canonical core scans the
composed envelope once and splices the already parsed, already target-selected
root segments in at each placeholder, at their authored positions — so an
unwrapped run is the run it always was, and an authored `<Document />` is an
ordinary element that projects nothing. Execution, `inspectDocument` and
document validation compose the root through one shared path.
The #817 review graph becomes the first production Plugin:
`@executablemd/code-review-agent` exports it as the package default, built from
the existing `reviewComponentDeclarations()`/`useReviewComponents()` boundary
with all thirty-five declarations, six reserved registrations, origins, digests
and packaged assets unchanged. `packages/cli/src/bundled-plugins.ts` is now the
only CLI module that names the package, and one installation per command serves
ordinary execution, `xmd syntax`, structural validation and every `<Plan>`
check.
A selected Plugin is trusted executable code and is not sandboxed: loading one
runs its module. Refusals — no usable default export, no name, a non-callable
install, a duplicate Plugin name, a remote specifier — happen before any
install and before the root is read.
Copy file name to clipboardExpand all lines: architecture.md
+153-9Lines changed: 153 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -139,6 +139,10 @@ and categorization rather than clarify them, so both stay exactly as written.
139
139
| execution environment | the private bundle of services and records one execution supplies while its document expands: what resolves a name, what routes it to a retained implementation, what the execution declared, and the records it keeps about its own identities, forms, vocabulary and source output. The execution builds it from what it captured and admitted, owns it, and passes it by value through canonical expansion — never through a context, because a context resolves by name and a name is not a secret. An expansion driven directly is handed none at all, which is what "nothing is installed here" means; there is no partial one. Its shape is an architecture and product boundary |
140
140
| syntax reference | the engine-owned lexical answer to "what may a document write here", carried by value on canonical core's execution environment beside what resolves an import. The execution builds one at its root from the selection inputs it captured before any installation, middleware or document code ran, or from the one set of symbols a trusted host stated for its profile; a trusted canonical evaluation boundary replaces it for the subtree it evaluates. It answers with text and decides nothing: a component the symbols name is not a component anything may run |
141
141
| run profile declarations | the component registrations a first-party package makes, held as plain values apart from the middleware, providers, activation and launchers its installer also arranges. The installer registers exactly those values and inspection reads exactly those values, so what a run installs and what the symbols report cannot drift |
142
+
| Plugin | trusted code a distribution bundles or an operator selects with `--plugin`, installed once before an execution imports a root document. A plain structural value carrying a name and one optional `install`; what it contributes is the existing `ExecutionInstallation` members, and what it composes through are the three stable contextual APIs below. Selecting one runs its module and its code with this process's own authority: it is trusted, and it is not sandboxed |
143
+
| document envelope | the Markdown the `Document` Api composes for one run: the canonical `<Document />` placeholder wrapped by each Plugin's middleware, first Plugin outermost. Canonical core scans it once and splices the root's already parsed, already target-selected segments in at each placeholder, at their authored positions — so an unwrapped run is the run it always was, and an authored `<Document />` is an ordinary element that projects nothing |
144
+
| active Plugins | the frozen ordered list of Plugin values installed for one command, published before the first `install()` runs so that every Plugin and every later consumer read the same list. It is a description of what is installed and grants nothing |
145
+
| command declarations | every Markdown component one command declares, in one order: what the installed Plugins declared, then whatever the calling surface declares for itself. Built once per command so that an ordinary run, a nested `host="run"` child, inspection and `<Plan>`'s validation cannot describe four different vocabularies |
142
146
| origin-only | the inspectability of a component whose contract could only be learned by loading it: a repository TypeScript module, whose schemas live on its exports and whose top level would run. Such an entry carries name, category, origin and source kind, and no contract field at all — an absent contract is stated, never rendered as an empty one |
143
147
| definition-owned return state | which value body a `<Return>` selects for: one ephemeral state per execution of one value root or Markdown value component. Structural directives keep the ambient one, a component invocation hides it from the invoked body, a nested value body installs its own, and caller-projected content restores the caller's. It travels down the expansion call stack as a local rather than through a context, and no exported function accepts another body's, so nothing a document can read, replace, or import acts on a live one. The first claim on it is atomic, so a second executed return fails the body rather than replacing its value, and it appends no durable event |
144
148
@@ -4416,6 +4420,139 @@ durable is written.
4416
4420
`undefined`, and a replay reconstructs the same validated prop set through
4417
4421
ordinary expansion.
4418
4422
4423
+
## The Plugin boundary
4424
+
4425
+
A **Plugin** is trusted code installed before an execution imports a root
4426
+
document. A distribution names the ones it bundles, and an operator appends
4427
+
their own with a repeatable `--plugin <specifier>`. Together they are the one
4428
+
extension boundary XMD has: there is no package with a reserved name, no
4429
+
manifest, no Plugin version, no capability bag and no central runner context a
4430
+
Plugin reaches through.
4431
+
4432
+
**A Plugin is a value, not a registration.** It carries a name and, optionally,
0 commit comments