Skip to content

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 handle seam 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.

— export_web.rs:12-21

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 premiseHere
Needs a deployment and a URLLoopback, started by the person who owns the corpus. Unchanged.
Needs an exported bundle, so needs a corpus to exportReads the working tree it was started in. Unchanged.
Renders; computes nothingAuthors — but the thing that computes is now a subprocess, not this process.
A rendered shell is a derived repo's own objectAn 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 web already 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 violations array 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_version behind it fails a render test.
  • The @yidam/core boundary 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 .mcpb bundle 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 same cli/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, manifest yidam/editors/web/package.json, tag edit/v{major}.{minor}.{patch}, registry npm.
  • A release channel, and therefore a check in install-channels.yml that 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_version is 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.

  • --root is handed to the binary, and also sets its working directory. The original text said it "resolves exactly as serve --root does". When this was written that was right about serve and wrong about the five report commands this design spawns — lint, graph, graph-check, status, open-questions — which resolved by git rev-parse --show-toplevel from the working directory (paths.rs:5-9). They take --root since #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 --bind for 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-open suppresses 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 Origin is 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/streamflow in this one, or any checkout inside a larger workspace — could be read only by copying it somewhere else and running git init on the copy.

— main.rs:126-130

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 --mcp and serve --lsp — now carries --root beside the working directory. Three consequences:

  • A pin older than cli/v0.16.0 still works. Clap rejects --root on its report commands, so the run is repeated without the flag and the result is marked working-directory. The header then states the overshoot and names the repair, a re-pin. serve has taken --root since 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 own Error: 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.

RouteServes
GET / and the app's pagesAstro, server-rendered on @astrojs/node
GET /api/handshakeformat_version plus the CLI's version, commit and feature list — the fields report::YidamBlock::current() assembles
GET /api/corpusyidam graph --format json, whose nodes and resolved edges come from model::corpus_nodes() — the function serve, graphml and rdf already share
GET /api/reportslint 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/cycleThe 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.toml records 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.

— binary.ts:8-11

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 out edges 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.

— graph.ts:19-24

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 package copies only what lives under the crate root. An include_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.

— packaging.rs:1-19

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_with walked 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_instances adds the buffers the walker would have accepted, and the server declares it — experimental.yidam.unsavedInstances in the initialize result (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. publishDiagnostics is 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 with null, and does so after the publishes a preceding change produced — a_request_after_a_change_is_answered_after_its_diagnostics pins the order. The bridge sends $/yidam/barrier after every didChange and 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 LspClient frames Content-Length over stdio and correlates ids; one OverlayBridge per 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 a status with 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) — an unavailable that 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 so missing-property names 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 --lsp children, 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, not yidam propose. The obvious frame — spawnReport with a different argv — would have been the second route RFC-0029 §2.2 forbids: yidam propose is a person's command and carries none of the tier. The [serve] act = true declaration, the startup refusal on a checkout with no author, and the frozen capability-not-supported shape all live behind handle, 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_eof pins, 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 POST from a browser page always carries Origin, so the route requires it and refuses any other method with 405 (actRefusal). Building it found that Astro's own cross-site check had been refusing every same-origin POST — it compares against a url.origin it synthesises as http://localhost unless the host is listed — so astro.config.mjs:39 lists 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, so edit-released in install-channels.yml resolves 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 two vsce refusals 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 build fails on a published page the sidebar does not reach. That is true and does not apply: the web editor is a third section of editor-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: act is gated on the criterion; the transport is evidence for the criterion, never the rule. A loopback server started by the corpus's owner MAY declare act. 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.

  1. A git author identity resolves for the serving process, in the corpus it serves. Met, and the Node process does not weaken it. yidam-edit writes 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 one git resolves 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.
  2. 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.
  3. Every listening socket the act-declaring server holds is loopback. Met by construction and more strictly than required — this surface has no --bind at all (§ The command surface), so there is no configuration under which it binds wider and no startup check to write.
  4. 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 act is 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-fixture stages 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 an Outcome. 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 at f3b203e.
  • 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 web into an editor. Rejected. An export is opened over file:// 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/react is 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? serve and export do; lint, graph, graph-check, status and open-questions do 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.ts and handshake.ts get extracted, or copied? Both are vscode-free and both are needed here, but importing them across package roots is the npm publish failure 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.

  • tsx is not in the design gate's scope. 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 — design_tokens.rs:169-171: "A consumer is any file of a [CONSUMER_EXTENSIONS] type outside yidam/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 was css, astro, jsx, so this surface was covered for free if its islands were .jsx and 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.jsx and Propose.jsx each carried a comment saying the island is .jsx because the gate reads jsx and not tsx — 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_EXTENSIONS is now astro, css, jsx, ts, tsx. ts as well as tsx, because CSS does not need JSX around it: the extension's webview stylesheet is a template literal in neighborhood.ts spending 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-lint lints the repository, not yidam/design. Its one live rule forbids reaching past index.js into 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 ts and are worth reading as part of the settlement. HOST_PREFIXES exempts --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.json that 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. No client:* 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-dev against the reports golden corpus, driven with headless Chrome over the DevTools protocol. The island hydrated (Astro's runtime cleared its ssr marker); the design system's Input is a controlled component and its onChange reached React — typing narrowed the table from 4 rows to 1; its useState focus ring worked under a real click, with --border-focus and --shadow-focus-gold resolving 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.mjs asserts the island is still shipped and that Input'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 declare act. 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 new act tool 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 is propose's, and propose lands on a propose/<head> branch with HEAD unmoved; the baseline is changed by a person merging a branch they reviewed as commits. A button that committed the working tree would be an act tool 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 driving git commit on the host deserves its own argument before it deserves a route.

  • The port, and coexistence. --http defaults 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 supervised serve --lsp child makes the second half of the question sharper than it was: two editors, two children, one corpus.