RFC-0030 — The surface is beside the binary, and earns a version (yidam-edit)
- Status: Draft
- Track: I25
- Relates to:
- RFC-0016 (the editor surface this is the third client of, and whose boundary it inherits — no longer unbreakable, and therefore guarded)
- RFC-0001 (the JSON report contract it renders, and now the contract it negotiates on)
- RFC-0029 (the write tier this defers its authoring path to rather than inventing a second one; this surface was the case that made its identity gate read on the criterion rather than the transport, settled 2026-09-05)
- RFC-0005 (the
handleseam whose framing argument this repeats at a second transport) - RFC-0025 (the design system this consumes, and the adherence gate that does not yet see the file types it would be written in)
- Versioning layers touched: Layer 4. This surface is a third artifact in the tooling layer, versioned and released on its own tag. The row lands with its publish path and its channel check, never before — see § The fifth artifact.
- Downstream reference case: Project BOSC (watermark-directory)
Amended 2026-09-05. This RFC was written on the claim that the surface is not a fifth artifact: served by the binary that computes the verdicts, cut on the same
cli/v*tag, with no npm package, no second runtime, and no new row in Layer 4's table. The owner has reversed that decision. The proposal is now the shape this document originally filed first under § Alternatives considered — an Astro application on@astrojs/node, published to npm, versioned and released on a tag of its own.Two arguments carried the original and both are withdrawn. The overlay is no longer computed in the process that serves the page, so it costs a bridge; and a Node process is no longer impossible, so RFC-0016's boundary stops being unreachable-by-construction and becomes a rule that has to be guarded. This document does not soften either cost — it states the price in § The overlay crosses a process boundary and § The boundary, now breakable, and quotes its own original objection where that objection was right.
What the reversal buys is in § The fifth artifact: a development loop that does not rebuild a Rust binary to move a button, a distribution route that does not put megabytes of hashed assets in a crate, and two modules the extension already carries that this shape can use and the embedded shape had no use for.
Summary
yidam has two editor surfaces and both require a configured editor to reach. serve --lsp
needs an LSP-capable editor and a config block a person writes by hand; the VS Code extension
needs VS Code, and — until #314 — a .vsix sideloaded from a GitHub release, because Open VSX
does not serve VS Code proper (VERSIONING.md § Layer 4).
Neither reaches somebody who has a corpus and a terminal.
This RFC proposes yidam-edit: a local authoring surface, an Astro application on
@astrojs/node, published to npm and run against a checkout — npx @goedelsoup/yidam-edit — whose node
forms are generated from the ontology rather than typed as YAML, and which computes no verdict
of its own. Every judgement it renders comes from the yidam binary the repository pins,
resolved the way the extension resolves it and spoken to over the contract RFC-0001 froze.
The load-bearing claim is no longer about the UI, and it is no longer that this costs nothing. It is that a third client of one contract is worth a third row in Layer 4, and that the row carries the obligations every other row carries.
Problem
Both editor surfaces are reached by people who already have the tools
docs/editor-setup.md is, correctly, two configuration recipes and an
extension install. Everything it asks for is reasonable and none of it is free: a Neovim user
writes an autocmd, a Helix user edits languages.toml, a VS Code user downloads a .vsix
because the registry route does not exist yet. The population that has installed yidam and
has no configured editor for it is served by nothing, and it is the population a bootstrapped
repository produces — genesis is an agent dialogue, and the person on the other side of it did
not necessarily arrive with an editor already pointed at a corpus.
This is #420's sentence — every surface arrives in a terminal — applied to the one surface
that currently does not. npx is a terminal, and it is one the target population already has:
this surface's whole premise is a person who has not configured an editor, and the shortest
route to a page for that person is one command that installs and runs in the same breath.
A structured document is being edited as free text
A corpus node is not prose with links in it. It is a typed record:
class: gage
label: Canyon Outlet gage
description: |
… prose carrying [verified] / [inference] / [open] tags …
properties:
parameter: "00060"
units: cubic feet per second
claim_tag: inference
links:
- target: ../gage.ont.yml
relationship: instance-of
(examples/streamflow/.yidam/corpus/gage/canyon-outlet.yml)
The class declares its properties and the edges it licenses; the claim tags are a closed set
of three; the commit that carries the change is drawn from a closed vocabulary. Every one of
those is a control, and in both existing surfaces every one of them is typed by hand into a
text buffer and checked afterwards. The gap is not that the checks are missing — they are
excellent — it is that the authoring affordance stops at completion in a line of YAML.
The repository already ships a web UI, and this is not it
export --format web embeds a static site in the CLI and writes it out — include_str! over
assets/web/, with the design system concatenated into the
binary by build.rs from _ds_manifest.json
(export_web.rs:12-21). That page is opened
over file:// with no process behind it, which is exactly why the design system had to travel
inside it:
An exported page is opened over
file://and cannot fetch anything, so the system travels with it — which is the constraint that produced a hand-copied subset before #465, and ten drifted values with it.
What is proposed here differs on both counts. There is a process, so nothing has to travel; and that process can ask the binary a question, so the page can carry a verdict rather than a snapshot of one. The earlier draft of this RFC read the export as prior art for embedding a UI in the binary. It is better read as the measurement of what a UI with no process behind it costs.
A web surface was already killed, and one of its premises has come back
#236 closed by decision: packages/web/ was a browser shell over an exported .yiz bundle,
with no deployment and no public corpus to render, and the owner's settlement recorded that a
rendered shell is a derived repository's own object — kuten territory (#573/#582) — not a
template surface.
That reasoning is about a deployed reader over an exported artifact. Under the original shape three of its four premises were absent. Under this one, two and a half are:
| #236's premise | Here |
|---|---|
| Needs a deployment and a URL | Loopback, started by the person who owns the corpus. Unchanged. |
| Needs an exported bundle, so needs a corpus to export | Reads the working tree it was started in. Unchanged. |
| Renders; computes nothing | Authors — but the thing that computes is now a subprocess, not this process. |
| A rendered shell is a derived repo's own object | An editor is tooling a person runs — Layer 4's own definition. Unchanged. |
The third row is the one the reversal moved, and moving it is the whole cost of this document. A Node server that renders a corpus and shells out for its verdicts is one refactor away from a Node server that renders a corpus and computes them, and that server is #236 with a package.json. § The boundary, now breakable is what stands between the two, and it has to be a gate rather than a paragraph.
The fourth premise remains the one to watch: if yidam-edit were ever pointed at a bundle and
deployed, it would be #236 wearing a new name.
§ What this deliberately is not closes that door explicitly.
RFC-0016 rejected a web app, and named the reason
A web app instead of an editor. Rejected as a substitute;
export --format webalready exists and serves reading and retrieval. It cannot put a squiggle under the link you just mistyped, which is where the friction actually is.
That rejection is correct and this RFC does not overturn it. It rejected a reader offered as a substitute for an authoring surface. What is proposed here can put the squiggle there — § The overlay crosses a process boundary is how, and what it costs — and it is offered as a third client of the same contract, not as a replacement for either existing one.
Proposal
The boundary, now breakable
TypeScript computes affordances. The CLI computes verdicts.
RFC-0016's rule applies verbatim, and the original draft of this RFC observed that under the embedded shape it was not merely forbidden but unreachable: with no Node process anywhere, the JavaScript that shipped could not compute a verdict because it had nothing to compute one from.
That property is gone. There is now a Node process holding a parsed corpus, and every check in this repository is a pure function over exactly that. The failure mode the rule guards against — a TypeScript re-derivation of a check, standing beside the real one and disagreeing with it — is reachable in this design by a contributor with good intentions and an afternoon.
So the rule stops being a sentence in an RFC and becomes a gate. Three, specifically, and Phase 1 carries them rather than Phase 4:
- No check names in the server's dependency graph. A test asserts that nothing under the
app's server directory imports a corpus-evaluating module, and that the only source of a
violationsarray is a process spawn. - Every verdict the page renders is traceable to an envelope. The page renders findings from
a parsed RFC-0001 envelope and from nowhere else; a finding with no
format_versionbehind it fails a render test. - The
@yidam/coreboundary is drawn explicitly. The TypeScript SDK is a parity surface with real corpus logic in it, which makes it the single most likely accidental route to a re-derivation. It is available for types and for affordances; a server route that calls its evaluating functions fails the first gate above.
This is the price of the reversal, paid where it falls due. It is not a smaller amount of work than the embedded shape's asset pipeline; it is a different kind of work, and it protects something more valuable.
The fifth artifact
VERSIONING.md, on the .mcpb bundle, argues the case this RFC originally borrowed:
The
.mcpbbundle is not a layer, and does not earn a version. #421 asked which, and the answer is neither: a bundle is the CLI binary in a different wrapper, cut on the samecli/v*tag by the same workflow step that cuts the tarballs, and its manifest carries the version of the binary inside it. Giving it a version of its own would put the CLI's version in a second place.
The clauses do not transfer, and the reversal is the recognition that they never quite did. A
.mcpb bundle contains the binary; yidam-edit contains no binary and resolves one at run time.
Its version is not the CLI's version in a second place, because it is not the CLI's version at
all — it is a statement about a client, released on a cadence a button change should be allowed
to have and a corpus-lint fix should not be forced into.
That is Layer 4's existing argument about the extension, applied a third time:
A Marketplace release needs a public, semver-shaped version and its own cadence; a CLI patch should not imply an extension release, and an extension patch should not imply a CLI one. Neither version is what the two negotiate on.
So:
- A third row in Layer 4's table, artifact
@goedelsoup/yidam-edit, manifestyidam/editors/web/package.json, tagedit/v{major}.{minor}.{patch}, registry npm. - A release channel, and therefore a check in
install-channels.ymlthat asks npm what it serves — for the reason #231 established: a channel with a publisher and no check is an artifact that builds while nobody has asked whether it can be obtained. format_versionis now involved, and this is the sharpest consequence of the reversal. The handshake exists because a client is versioned independently of the binary it talks to, and this client is exactly that. It reads the envelope first and degrades loudly on an unknown major, as RFC-0016 requires and as the extension already does.
The row lands with its publish path and its check, or not at all. VERSIONING.md's own rule:
This table names registries this project delivers to, never ones it intends to.
the_registries_layer_4_names_are_delivered_and_checked refuses a row whose publish path and
channel check are not there with it — the same test that holds the Marketplace row out. So the
row, the npm publish step and the channel check landed together in Phase 4, as one change.
#232 is what the other order costs: cargo binstall yidam stood in the README for a release
cycle while yidam did not exist on crates.io.
The name, settled 2026-09-18
@goedelsoup/yidam-edit, decided by the repository owner on #610.
This RFC's lean was @yidam/edit, and it is declined. The argument for it was consistency with
@yidam/core, which is in-tree and
unpublished — consistency with something unpublished, used as the basis for a blocking
dependency, since the @yidam scope would have had to be registered before the row could be
written truthfully.
The check that decided it is worth recording, because the obvious one gives the wrong answer. A
GET https://registry.npmjs.org/<pkg> returns 404 for @yidam/edit, @goedelsoup/yidam-edit
and unscoped yidam-edit alike, and that only says those packages do not exist — a scope can
be held with nothing published under it. The endpoint that answers ownership is
GET https://registry.npmjs.org/-/org/<scope>/user: yidam answers 404 Scope not found, and
goedelsoup answers {"goedelsoup":"owner"}. It discriminates rather than answering 200 to
anything, so the 404 is evidence and not silence.
Owning the identity elsewhere is not owning the npm scope, and nothing unauthenticated can
tell whether a held handle belongs to this project or to a namesake. That question was the
owner's, and the answer was yes: the npm account goedelsoup is this project's. So
@goedelsoup/yidam-edit is the only candidate needing no registration on the day the Layer 4
row is written, which is exactly what VERSIONING.md's rule asks for. It is also the handle the
VS Code extension already publishes under, so the two things a person installs live under one
name rather than two.
yidam-edit unscoped was viable — shortest to type, and npx is this surface's whole entry
point — and was declined for that identity reason. Unscoped names are first-come and cannot be
reserved without publishing, which is a cost the scoped name does not carry either.
The command surface
npx @goedelsoup/yidam-edit [--root DIR] [--port N] [--no-open]
The yidam binary gains nothing. There is no yidam edit subcommand, no route table in
http.rs, and no new Rust feature — a consequence of the reversal worth stating plainly, since
the original design put all three in the CLI.
--rootis handed to the binary, and also sets its working directory. The original text said it "resolves exactly asserve --rootdoes". When this was written that was right aboutserveand wrong about the five report commands this design spawns —lint,graph,graph-check,status,open-questions— which resolved bygit rev-parse --show-toplevelfrom the working directory (paths.rs:5-9). They take--rootsince #918 (cli/v0.16.0), and the surface passes it since #1012; a pinned binary older than that is asked again without the flag. See § A corpus inside a corpus.- Loopback only, and not configurable. The original offered
--bindfor a container; this one does not, because a server that authenticates nobody and now has a Node process in it should not carry the flag that turns it into #236. A container reaches it by publishing a port, which is the container's decision to make rather than this server's. --no-opensuppresses the browser launch, for a remote shell.- Origin is checked, not configured. The only legitimate client is the page this server
served, so any other
Originis refused rather than allowed by a flag.
A corpus inside a corpus
Found by running Phase 1's scaffold rather than by reading, and it belongs in this document because it is a property of the seam this design chose, not of the code that hit it.
When this was written --root existed on serve and on export alone. It is on every
reading command since #918, whose shared declaration says why:
The reasoning generalised long before the flag did: every command resolved its corpus from the working directory, so a corpus that lives inside another git repository —
examples/streamflowin this one, or any checkout inside a larger workspace — could be read only by copying it somewhere else and runninggit initon the copy.
The five commands this surface spawns did not have the flag when this design was chosen, so
yidam-edit --root DIR sets the child's working directory and inherits exactly the behaviour
the quotation describes: pointed at examples/streamflow inside this checkout, every report
answered about the outer repository, and the browser showed a corpus with no nodes in it. An
empty corpus and a wrong corpus render identically, which is what makes this worth a
paragraph rather than a bug — and it remains true of the working directory even now that
passing the corpus along is available.
Phase 1 does the honest minimum: every envelope carries root, so the surface compares what
it asked for against what answered and says so in the header when they differ. That is
degrade-loudly applied to a question the handshake does not cover.
The real fix is a --root flag on the report commands, and it is the CLI's to make, not this
surface's — restating the resolution rule in TypeScript would be the second copy the parity
apparatus exists to prevent.
Amended 2026-09-29 (#1012). The CLI made it (#918), and every spawn from this surface — the five reports,
serve --mcpandserve --lsp— now carries--rootbeside the working directory. Three consequences:
- A pin older than cli/v0.16.0 still works. Clap rejects
--rooton its report commands, so the run is repeated without the flag and the result is markedworking-directory. The header then states the overshoot and names the repair, a re-pin.servehas taken--rootsince cli/v0.10.0, below the act tier's floor, so it gets no fallback.- The header check stays, with a second cause. Handed
--root, the binary walks up to the nearest.yidam/, so a directory inside a corpus answers for the corpus around it. That is correct, and the header says which corpus it is without suggesting a repair.- A wrong path is now a refusal, not an empty page (#1000). The refusal has no envelope, and the handshake would read that as a binary predating
--format json. So the binary's ownError:text is what the page shows.
How it reaches a verdict
The server spawns the pinned binary per request and parses the envelope. Nothing else.
| Route | Serves |
|---|---|
GET / and the app's pages | Astro, server-rendered on @astrojs/node |
GET /api/handshake | format_version plus the CLI's version, commit and feature list — the fields report::YidamBlock::current() assembles |
GET /api/corpus | yidam graph --format json, whose nodes and resolved edges come from model::corpus_nodes() — the function serve, graphml and rdf already share |
GET /api/reports | lint and graph-check as the RFC-0001 envelope, byte-identical to --format json |
GET /api/overlay (SSE) | Diagnostics from a supervised yidam serve --lsp — see below |
POST /api/act/propose, POST /api/act/cycle | The two tools of RFC-0029's act tier, through yidam serve --mcp — one stdio connection per request, three lines down and two back (act.ts:136). ?dry_run=true is the tool's own argument; force has no field to arrive in. Landed 2026-09-22 (#608) |
Binary resolution is the extension's, and this is the one place the reversal is free.
binary.ts and
handshake.ts are already vscode-free by
deliberate design — "everything here is a pure function over inputs the extension host
supplies, so it is testable with node --test and needs no Electron" — and they encode two
rules this surface must obey and would otherwise re-derive:
The extension never bundles, downloads, or builds a binary. A derived repository's
.yidam.tomlrecords which yidam commit governs its corpus; installing some other one behind the user's back would make the editor's verdicts disagree with CI's, which is the single failure this whole surface exists to avoid.
The embedded shape had no use for either module — a binary serving its own UI knows its own version and its own path. This shape needs both, and they exist.
The overlay crosses a process boundary
This is what makes the surface an editor rather than a viewer, and under the reversal it is the most expensive thing in the document. The original said so, about this design, and was right:
This is the single strongest technical argument for serving the editor from the binary rather than from a Node process that would have to bridge stdio LSP to a WebSocket to get the same answer.
That bridge is now the plan. Overlay is a
pub struct in the lint module, and
run_checks_with is the entry point the language
server calls on every change (lsp.rs:250) — but it is
reachable only through serve --lsp. yidam lint has no overlay flag, and the extension is no
prior art here: it carries no LSP client and no dependencies at all, running lint --format json
against the tree and building diagnostics itself.
So the server supervises one yidam serve --lsp child per corpus, sends buffer text as
textDocument/didChange, and relays publishDiagnostics to the browser over server-sent
events. The squiggle is drawn by the function that draws it in Neovim, with no second
implementation to drift — the boundary holds — and there is now a process, a protocol and a
lifecycle between the browser and that function. Process supervision, LSP framing over stdio,
and a child that dies mid-session are three failure modes the embedded shape did not have. They
belong to Phase 2 and are the reason Phase 2 is no longer the cheap phase.
Forms from the ontology — and the trap already found
A class declares its properties and its out edges, so a node form can be generated rather
than typed. The obvious next step — restrict the relationship picker to declared edges — is
wrong, and the extension already measured why:
Measured against a live derived repository at 90 nodes and 299 edges: 17 of the (class, relationship) pairs actually in use are not declared as
outedges on their class, and one of them —instance-of, the edge every node carries to its own.ont.yml— is used by every class and declared by none. Nothing lints relationships against the ontology, so a completion list restricted to declared edges would be stricter than any rule in the system and would omit the corpus's single most-used relationship.
The form adopts that finding rather than rediscovering it: declared edges first, relationships
already in use beside them, and the reason each is offered shown next to it. A form is a
stronger nudge than a completion list, so getting this wrong here is worse than getting it wrong
there — a picker with no free-text escape would make instance-of unwritable.
The same distinction governs the rest of the form. The commit vocabulary is closed and is gated, so the commit affordance may constrain to it. Claim tags are three and closed. The ontology is a guide. Three sources, three different strengths of constraint, and the form has to carry the difference.
Note what the reversal does not change here. Reading the ontology to build a form is an affordance, not a verdict, and it was on the TypeScript side of RFC-0016's line under both designs.
Where the sources live, and what ships
Sources at yidam/editors/web/, a sibling of vscode/ under
yidam/editors/, which already exists as the index of editor
surfaces. Grouped by surface rather than by technology: the extension's binary resolution and
handshake modules are the closest prior art, and RFC-0016's split is a split of surfaces.
Nothing is committed, and nothing is embedded. The whole asset question the original spent a
section on is dissolved by the reversal: npm publish ships a build produced in CI, cargo package never sees it, and the crate root is untouched. The staleness gate, the crate-root
symlink and the packaging.rs assertion are all withdrawn — that section existed to answer a
question this shape does not ask.
One clause of it does transfer, and it is worth carrying over rather than rediscovering:
cargo packagecopies only what lives under the crate root. Aninclude_str!whose path escapes it … resolves in the working tree and in every CI job, because the tree is right there, and is simply absent from the tarball.
npm publish has the identical property with an identical failure signature: a module imported
from outside the package root resolves in the working tree and in every CI job, and is absent
from the tarball. So the app carries every module it ships under yidam/editors/web/, and a
packing test asserts the published tarball runs — the same check, one ecosystem over, learned
from two near-misses this repository has already paid for.
Phases
Phase 0 — this RFC and this amendment. The decisions above are the deliverable.
Phase 1 — the read surface. npx @goedelsoup/yidam-edit serving an Astro MPA for browse / node /
reports / open-questions / status, against the design system's components. Binary resolution and
the handshake, both from the extension's modules. The three boundary gates from
§ The boundary, now breakable land in this phase, before there
is anything for them to fail on — a gate written after the code it governs is a gate written
around it. No writes, no overlay.
Phase 2 — the overlay, and the forms. The serve --lsp bridge, with supervision and a
lifecycle; class-driven node forms with the relationship rule above; claim tags as controls.
Still no writes to disk. This phase absorbed the reversal's cost and should be planned as the
largest of the four, not the second-cheapest.
Landed 2026-09-22, #607. Two routes, one page, and one CLI change. Five things it settled by being built:
- The overlay did not know a buffer was a node.
run_checks_withwalked the corpus for instances and unioned the overlay over those paths, so a buffer for a file not yet on disk was seen by no check at all: its findings were exactly none, which is what a clean node's are. The editors never noticed because every buffer they send is a file that exists.Overlay::unsaved_instancesadds the buffers the walker would have accepted, and the server declares it —experimental.yidam.unsavedInstancesin theinitializeresult (lsp.rs:418) — so a bridge on an older binary can say saved nodes only rather than show a clean verdict it did not earn. - The barrier is an unknown request.
publishDiagnosticsis a notification, and a clean buffer publishes nothing new, so a page cannot tell clean from not judged yet. The server answers any request it does not know withnull, and does so after the publishes a preceding change produced —a_request_after_a_change_is_answered_after_its_diagnosticspins the order. The bridge sends$/yidam/barrierafter everydidChangeand treats the reply as the verdict's edge (overlay.ts:396). No protocol extension, and nothing in the server knows the bridge exists. - The three failure modes are three tests, and a budget. One
LspClientframesContent-Lengthover stdio and correlates ids; oneOverlayBridgeper process supervises the child: the first page starts it, the last page's leaving shuts it down politely and kills it if it will not go, and the process-exit hook kills it outright. A child dying mid-session is broadcast as astatuswith the exit and its stderr tail, the page marks its verdicts stale and says verdicts stopped, and the next change restarts the child and replays every held buffer. Three starts inside a minute is a binary that cannot run here, and the bridge stops trying rather than spawning a fourth (START_BUDGET) — anunavailablethat is sticky for the process, because a loop that retries every keystroke is the leak wearing a different coat. - The form's relationship picker carries the tier. Declared out-edges first with their
targets, then relationships the class's own instances use with the count, then what other
classes use, then a free-text row — every option shows why it is offered
(
relationshipOffers). The three claim tags are a closed select and insert buttons under the description; the ontology is a guide. The buffer is a one-way render of the fields, and editing it detaches the form rather than parsing YAML back — a second reader of a document the binary already reads was the thing not to build. Empty properties are omitted somissing-propertynames them: the sandbox's whole point is the verdict, and a form that filled in""would be hiding it. - Two things it does not do, and why. It does not edit an existing node. The graph
report carries a node's class, label, description and links, and no property values, so a
form opened on a saved node would render its properties blank — the read that would fill
them is a report change, filed rather than faked. It does not share a child with the
extension. Two editors on one corpus is two
serve --lspchildren, each with its own overlay; they agree because they run the same function, and the day they disagree the cause is a stale pin, which the header already shows.
Phase 3 — writes. Gated on RFC-0029's build. The decision half is
Accepted, and its identity gate reaches this surface — see
§ The identity gate, answered,
which is why #427 is not in this phase's dependencies. The editor's writes are act's operations
behind a second framing, for the reason http.rs:9
gives about the first: "Not a second contract. super::handle is the seam RFC-0005 left for
exactly this."
Landed 2026-09-22, #608, independently of Phase 2. The build it waited on arrived in #864, and the phase shipped as two routes and one page. Three things it settled by being built:
- It spawns
yidam serve --mcp, notyidam propose. The obvious frame —spawnReportwith a different argv — would have been the second route RFC-0029 §2.2 forbids:yidam proposeis a person's command and carries none of the tier. The[serve] act = truedeclaration, the startup refusal on a checkout with no author, and the frozencapability-not-supportedshape all live behindhandle, so the editor speaks the protocol to a child for exactly one call and reads the answer off stdout.a_one_shot_connection_answers_both_ids_and_exits_at_eofpins, on the CLI side, that a three-line frame followed by EOF is a conversation the server finishes. - It did not need Phase 2.
propose's whole input schema is{ dry_run }(tools.rs:294); it drafts from the gate's findings on the committed corpus and refuses a dirty.yidam/(write.rs:110). Nothing a form produces can reach it. The two phases were ordered by an assumption that a write takes content, and this one does not. - The method rule is the origin rule doing more work. A
POSTfrom a browser page always carriesOrigin, so the route requires it and refuses any other method with405(actRefusal). Building it found that Astro's own cross-site check had been refusing every same-originPOST— it compares against aurl.originit synthesises ashttp://localhostunless the host is listed — soastro.config.mjs:39lists the loopback names. Two checks that agree, not one switched off.
Phase 4 — the artifact, and the gates. The Layer 4 row, the npm publish path and the
install-channels.yml check, landing as one change. A ci-editor-web mise task and a CI job
mirroring vscode; a Dependabot npm group; a row in editor-setup.md and
in yidam/editors/README.md.
Landed 2026-09-22, #609. Four things it settled by being built:
- The name is
@goedelsoup/yidam-edit— § The name. - The publish path is
edit.yml, a fifth tag pattern and the first Layer 4 artifact whose release creates no GitHub release. npm is its only channel, soedit-releasedininstall-channels.ymlresolves the version from the tag rather than from the releases API — the one resolution in this repository that had no release list to read. - The packing test is
scripts/check-package.mjs, and it runs on every pull request rather than first at the tag. #871 is why:ci (vscode)never packaged, so twovscerefusals were green for weeks and both arrived during a release. It packs, installs the tarball's production dependencies into a directory outside this repository, and starts the server there. A module imported from outside the package root, or a runtime import that is only a devDependency, fails at that start rather than on a stranger's machine. - No sidebar entry was needed. This phase's plan said one was, on the grounds that
astro buildfails on a published page the sidebar does not reach. That is true and does not apply: the web editor is a third section ofeditor-setup.md, which the sidebar has always listed, and no page was added.
The identity gate, answered — and what the reversal does to the answer
This section used to argue a case and decline to settle it. It has been settled, elsewhere and in this surface's favour: RFC-0029 was amended on 2026-09-05 and moved to Accepted, naming this surface as the counterexample that forced the question.
Decision:
actis gated on the criterion; the transport is evidence for the criterion, never the rule. A loopback server started by the corpus's owner MAY declareact. A server reachable from another machine MAY NOT until #427 supplies an author, exactly as written above.
So Phase 3 does not wait on #427. Its dependency is RFC-0029's build and nothing else.
The reversal happened after that argument was made and before it was written down, so the honest thing is to check the settlement against the shape that actually ships rather than the shape it was argued about. RFC-0029 gives four clauses an implementer checks. Three are decidable and this surface meets them; the fourth was already honest about what no server can see.
- A git author identity resolves for the serving process, in the corpus it serves. Met, and
the Node process does not weaken it.
yidam-editwrites nothing itself: a write is the spawned binary's, and that binary is a child of the Node process, which is a child of the person's shell, running in their checkout. The identity the commit takes is the onegitresolves there. This is the clause the reversal was most likely to break and does not — the earlier draft of this section supposed the author would be resolved by the Node process rather than inherited through it, and that is not how the spawn works. - The declaration is configuration, never inference. Met by not being reached yet: nothing
in Phase 1 or Phase 2 declares
act, and Phase 3 must be told to. - Every listening socket the
act-declaring server holds is loopback. Met by construction and more strictly than required — this surface has no--bindat all (§ The command surface), so there is no configuration under which it binds wider and no startup check to write. - That the peer is that person is a declaration the operator makes, not something the server
detects. Unchanged, and RFC-0029 states it plainly: every socket transport has an unbounded
peer set, and
actis configuration precisely because the fact being declared is not observable. This surface adds no authenticator and claims none.
What the reversal does change is which process the declaration attaches to, and that is a
Phase 3 question rather than an open one: the capability is declared by whatever speaks the MCP
contract, and under RFC-0029's own rule this surface reaches the tier through super::handle
rather than beside it. It is not a second route into the write tier, and RFC-0029 says so.
How it is tested
- The extension's fixture is reused, not rebuilt:
mise run ext-fixturestages the reports golden corpus as a real repository, and the app is driven against that. What CI checks and what a person sees stay one repository, which is why the task exists. - Route handlers take plain values and return them, following
http.rs's stated discipline — "Everything that decides whether a request is served … takes plain values and returns anOutcome. None of it needs a socket" — so the policy is unit-testable without binding a port. The discipline is worth copying across the language boundary precisely because this side is the one that can now cheat. - The boundary gates are tests, not review notes. See § The boundary, now breakable.
- The design gate covers this surface only if the file extensions match. See § Open questions.
What this deliberately is not
- Not deployable, and not deployed. No hosted instance, no bind address in any documentation, no path over an exported bundle. Any of those makes it #236, and #236 is closed by decision. This clause matters more under the reversal than it did under the original, because the original had no server that could be deployed.
- Not a second MCP surface. Agents have
serve --mcp. Nothing here is reachable by one. - Not a re-implementation of any check. The boundary is RFC-0016's, unchanged in what it requires and newly guarded in how it is held.
- Not a replacement for the extension or the LSP. Three clients, one contract. A person with a configured editor should keep using it; this is for the person who has not got one.
- Not a bootstrap wizard, for RFC-0016's reason: genesis is an ontology dialogue with an agent, and a form that skips the dialogue produces the unconsidered ontology the dialogue exists to prevent.
- Not a sangha surface. Positions and resolutions are governed by the constitution; RFC-0016 put anything that writes one out of scope pending the governance RFCs, and that holds here.
Migration & compatibility
Nothing in a derived repository changes, and .yidam.toml gains nothing. The CLI is untouched:
no new subcommand, no new feature, no route added to http.rs, and no growth in the binary —
the size question the original deferred to Phase 1 does not arise.
What changes is the release surface. Layer 4 goes from two artifacts to three, a fifth channel
becomes a sixth, and edit/v* joins cli/v* and editor/v* as a tag pattern a workflow must
trigger on and no other layer may fire. VERSIONING.md's standing rule applies to all of it:
never bump a layer as a side effect of another layer's release.
format_version becomes load-bearing for a third client. It is "1" today and this surface
does not propose to move it.
Alternatives considered
- Served from the binary, with the assets embedded — the original proposal of this RFC, and
now the declined alternative. It is the cheaper shape on two axes that matter: the overlay is
an in-process function call rather than a supervised LSP child, and RFC-0016's boundary is
unreachable rather than guarded. It was declined for the development loop it forces — a Rust
rebuild to move a button — for the megabytes of hashed build output it puts under the crate
root and into every
cargo install, and for the versioning claim it required, that a UI released on the CLI's cadence is the same artifact as the CLI. The full original argument is preserved in this document's git history atf3b203e. - Static assets over
serve --mcp --http, read-only. This is #236's shell with a different data source. It cannot author, and the MCP contract is read-only by construction (tools.json— thirteen tools, none of them a write). - Extend
export --format webinto an editor. Rejected. An export is opened overfile://with no process behind it; that is the constraint that forced the design system into the binary in the first place. Nothing there can compute a verdict, which is the whole difference. - A plain Vite/React SPA rather than Astro. Defensible, and Astro is chosen for two concrete
reasons rather than taste: the toolchain, the Dependabot group and the CI pattern already exist
for
yidam/web/docs, and@astrojs/reactis already how this repository's design-system components are consumed. Most of this surface — browse, node, reports, status — is content-shaped and wants an MPA; only the forms are islands. - A desktop application (Tauri, Electron). A new toolchain, a new signing story, a new channel, three new platform builds. Everything it buys over a loopback page is unrelated to the problem.
- Wait for RFC-0029 before starting. Rejected. Phases 1 and 2 are read-only and are the majority of the work; sequencing them behind a governance decision they do not depend on delays the useful part for the contested one.
Open questions
-
Which npm name, and who owns it.Settled 2026-09-18 — see § The name below. -
Should the report commands take
--root?serveandexportdo;lint,graph,graph-check,statusandopen-questionsdo not, and § A corpus inside a corpus is what that costs this surface. Phase 1 detects the mismatch and reports it, which is a workaround rather than an answer. Adding the flag is a CLI change with consumers beyond this one — the extension resolves a workspace the same way — so it is filed here and decided there. -
Do
binary.tsandhandshake.tsget extracted, or copied? Both arevscode-free and both are needed here, but importing them across package roots is thenpm publishfailure named in § Where the sources live. A shared module would be a fourth Layer 4 artifact unless it stays private, and a copy needs a parity test. Phase 1 carries a copy plus that test; the extraction is a decision this RFC does not force. -
Settled 2026-09-22 (#611): the gates read TypeScript, and the lint reaches its consumers. The consumer scan discovers surfaces by file extension, and says so —tsxis not in the design gate's scope.design_tokens.rs:169-171: "A consumer is any file of a [CONSUMER_EXTENSIONS] type outsideyidam/design/that references a token the system declares. The next UI kit is covered the moment it uses the palette, which is the point: a roster here would stop covering whatever came next." The list wascss,astro,jsx, so this surface was covered for free if its islands were.jsxand invisible to the raw-colour check if they were.tsx— #591's webview blind spot arriving a third time. Chosen 2026-09-06, in the narrow direction only: Phase 1's island is.jsx, which settled this surface and nothing else.That narrow choice was the wrong shape, and the reason is visible in the code it produced.
NodeTable.jsxandPropose.jsxeach carried a comment saying the island is.jsxbecause the gate readsjsxand nottsx— a constraint living in prose, enforced by whoever remembered it. That is the roster this RFC quoted the gate warning about, wearing a convention.So the list was extended, in three places rather than the two the issue named:
CONSUMER_EXTENSIONSis nowastro,css,jsx,ts,tsx.tsas well astsx, because CSS does not need JSX around it: the extension's webview stylesheet is a template literal inneighborhood.tsspending twenty token references, nine of them the palette's, which no gate in this repository had ever read.design_system.rs's prop scan reads.tsx— the third gate, which the issue did not name and which had the same hole: a TS island could pass a prop the component does not declare and React would drop it in silence.design-lintlints the repository, notyidam/design. Its one live rule forbids reaching pastindex.jsinto a component's internals, and every file in a position to do that was outside the path it was given — a rule that was live, fixture-proved, and unreachable.
Two things that came with
tsand are worth reading as part of the settlement.HOST_PREFIXESexempts--vscode-*, which VS Code injects into a webview and this repository cannot declare; the exemption is taken on trust, so it is one prefix long and every--vscode-…is now unread here. And the repository-wide lint pass suppresses oxlint's default category, because correctness has one home in the root.oxlintrc.jsonthat three packages extend — run with defaults on, that pass contradicts an exemption those packages make on purpose.What this does not settle is #591, which keeps the question it was filed for: the webview is now inside the scan — a raw hex or a dangling token in it fails a gate, which was proved by planting both — and nothing here decides whether that surface should be spending the palette rather than the editor's theme API.
-
The design system's React components have never been hydrated.Answered 2026-09-06: they survive. Noclient:*directive appeared on any quality page —astro.config.mjs:272-273: "this is a build-time renderer: React produces HTML and none of it is shipped to a reader." This surface is now the first consumer to ship them to a browser, and the spike was run rather than reasoned about:mise run edit-devagainst the reports golden corpus, driven with headless Chrome over the DevTools protocol. The island hydrated (Astro's runtime cleared itsssrmarker); the design system'sInputis a controlled component and itsonChangereached React — typing narrowed the table from 4 rows to 1; itsuseStatefocus ring worked under a real click, with--border-focusand--shadow-focus-goldresolving in the client bundle; the console was clean. Phase 2's forms may be built on these components. The half of that a browserless CI job can hold is held —test/hydration.mjsasserts the island is still shipped and thatInput's own code is in the chunk the browser downloads, because hydration working is a fact about React and Vite that does not silently change, while an island ceasing to exist is a one-character edit. -
Does RFC-0029's identity gate reach a loopback editor?Answered 2026-09-05 by RFC-0029's own amendment, which names this surface as the counterexample that forced it: the criterion governs, and a loopback server started by the corpus's owner MAY declareact. Phase 3's dependency is RFC-0029's build alone. Checked against the shape that actually ships in § The identity gate, answered. -
Does Phase 2 write at all? A form whose output cannot be saved is a strange object. The alternative is a small, editor-only write path that does not wait for RFC-0029 — which is a second answer to "how does something outside the corpus write into it", and is the thing this RFC is trying not to create. Narrowed 2026-09-22 (#608): Phase 3 shipped first and takes no content, so the question is no longer whether the forms wait on the write path — they do not — but what a form's save is. It is not
propose, which drafts from findings and never from a browser. A save is a newacttool with an input schema, which is a contract event under RFC-0005 and needs RFC-0029's argument made again for content that a person typed rather than a finding the gate computed. That argument is not made here, and no editor-only path was built in its place. -
Does a commit affordance belong here?Answered 2026-09-22, no (#608). The only write this surface performs ispropose's, andproposelands on apropose/<head>branch withHEADunmoved; the baseline is changed by a person merging a branch they reviewed as commits. A button that committed the working tree would be anacttool the contract does not have, with the same RFC-0005 cost as a form save and a larger claim — the extension's SCM box is VS Code-shaped, and a browser page drivinggit commiton the host deserves its own argument before it deserves a route. -
The port, and coexistence.
--httpdefaults to 8787. Whether this surface takes a neighbouring default, and whether both may run against one corpus at once, is unsettled and cheap to settle. The supervisedserve --lspchild makes the second half of the question sharper than it was: two editors, two children, one corpus.