docs(architecture): define-once separation contract — positron lowers onto Commands/Events#4
Merged
Merged
Conversation
… onto Commands/Events The four primitives are the "define once, project many" mechanism, but the separation of concerns was never written down — and the load-bearing decision (positron's session protocol vs the substrate's own command/event wire) was unresolved, risking two parallel dispatchers. docs/ARCHITECTURE.md pins it: - one (ViewState, command-vocabulary) definition → four surfaces collapse to two roles: Renderer (web/terminal/mobile) + Observer (AI persona → RAG/tool). - positron owns the view/render/perceive contract + wire semantics + session; it does NOT own a second dispatch bus. CommandEnvelope LOWERS to Commands.execute; StateEnvelope is produced by a projector over Events; the ContinuumHost is the single lowering seam. - constrains DESIGN.md open Qs #3/#4 to renderer-concern / semantic-only ViewState. - O1..O6 roadmap, one PR per unit; O2 (counter-cli) is next and makes this non-vapor. README + DESIGN cross-link the new doc. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LoTjvf5j3Ez13g6k8mRkFo
…uumHost phrasing, theming default Review (APPROVE WITH NITS) fixes: - use the established crate name `positron-lit` (not a new `positron-ts`); the npm types package stays `@positron/core`. Single name, one place. - soften "ContinuumHost already named in session.rs tests" → "referenced by name in a session.rs test comment (not yet a wired symbol)" — it's a prose mention, not an exercised symbol. - theming (open Q#3) framed as a strong default, not a primitive-enforced constraint: a theme token is arguably semantic, unlike layout geometry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LoTjvf5j3Ez13g6k8mRkFo
This was referenced Jul 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The first organizational unit for building positron out into the "define the app once for all environments" system Joel described. The four primitives (
ViewState/Renderer/Host/Observer) already encode "define once, project many" — but the separation of concerns was never written down, and the load-bearing decision was unresolved: does positron'ssession.rsprotocol compete with the substrate's own command/event wire (continuumipc/ws.rs)? Left unpinned, that grows two dispatchers — the exact 2000-line-widget anti-pattern positron exists to kill.The contract (
docs/ARCHITECTURE.md)(ViewState, command-vocabulary)pair; the four environments (web/terminal/mobile/AI) collapse to two roles —Renderer(web/terminal/mobile) andObserver(AI persona → RAG, acts viaCommandEnvelope). The persona is the fourth projection of the sameViewState, not a special case.CommandEnvelope→Commands.execute(one dispatch owner);StateEnvelopeproduced by a projector overEvents; theContinuumHost(already named insession.rstests) is the single lowering seam. The two-wire overlap withipc/ws.rsis resolved as layering, with the eventual merge flagged as an integration-time (O5) decision, not pre-decided.ViewState) from "lean" to "requirement" — oneViewStateserving a terminal + DOM + AI observer cannot carry geometry or theme.examples/counter-cliis next and makes this doc non-vapor (oneCounter, ≥2 renderers, 1 observer, in-process, zero transport).Scope
Docs only —
docs/ARCHITECTURE.md(new) + one cross-link each inREADME.mdandDESIGN.md. No code, no wire changes, no ts-rs regen. Pins the boundary before any renderer is written.🤖 Generated with Claude Code