docs(product): design embedded-mode revival — dual-mode returns, finish macOS (RIG-3139) - #833
Merged
Conversation
|
😎 This pull request was merged. |
|
Compass engineering docs preview: https://compass-native-rig-3139-embe.compass-eng-docs.pages.dev Deployed from Changed pages: |
rigel-mintaka
marked this pull request as ready for review
September 1, 2026 06:19
rigel-mintaka
force-pushed
the
compass-native/rig-3139-embedded-revival
branch
from
September 2, 2026 21:04
175698c to
792a67c
Compare
…sh macOS (RIG-3139) Designs the reversal of the RIG-2542 client-only retirement: mode="embedded" returns to the Compass native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode. The retirement's premise (the microVM Runner's KVM floor retiring local agent execution) is falsified now that podman is a permanent supported single-tenant tier per the trust-model boundary (DL-318, compass-obs #804). Covers the mode-selection contract, supervisor re-wire against the current stack, cross-OS preflight, bundle re-scope (sidecars return, postgres stays a DL-260 container), the macOS podman-machine provisioning spike, and the UI embedded boot arm. Records the record on the ui/ design path (RIG-3113 dissolved product/ into ui/) and lands the ledger delta in DECISIONS.md: new rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres); status flips DL-235/237/238 → Superseded by DL-319/320/321. DL-236's standalone-compass-stack half stays Active. Folds Matt's freeze-gate topology + backend feedback: the §Topology matrix separates the two independent axes (app mode: embedded/client; runner backend: podman/microVM) and records the recommended backend per funnel entry — embedded-local is podman-primary (macOS cannot do microVM; WSL2 has no KVM out of the box), self-host is microVM-recommended with podman the cost-sensitive tier, managed is microVM. Scrubs managed-hosted to the trust-model boundary only, with an OSS-core scope note keeping product-strategy specifics out of this repo. Adds three load-bearing open questions with recommendations for Matt's gate: OQ-9 (docker socket vs force-podman — force-podman: the --userns=keep-id:uid= isolation boundary is podman-specific), OQ-10 (apple/container as a macOS backend — defer: macOS-26 + Apple-silicon-only, pre-1.0), OQ-11 (embedded microVM on Linux — v1 container-only, follow-up). Also folds the prior review passes' podman-version FATAL preflight (delta 4, OQ-8) and the doc-comment reconciliations. Refs RIG-3139 Spec-impact: adds the embedded-mode revival design record (Draft) under docs/designs/ui/ Ledger-impact: DL-319/320/321 added; DL-235/237/238 flipped to Superseded Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-native/rig-3139-embedded-revival
branch
from
September 2, 2026 21:40
792a67c to
e429c68
Compare
mattwilkinsonn
approved these changes
Sep 3, 2026
trunk-io Bot
pushed a commit
that referenced
this pull request
Sep 3, 2026
…-323 (#851) A concurrent-merge window landed two records claiming the same ledger ids: #836 (RIG-2616 error/abort surfacing) allocated DL-318/319/320 off a pre-#833 main, but #833 (RIG-3139 embedded-revival), merged first, already held DL-319/320/321. The double-booked DL-319/320 fail design-ledger-gate:check on main ("duplicate ledger id"), which fail-fast-cancels the whole moon(bun) battery and blocks every open PR in the repo. Renumber this record's two rows to the next free ids (max on main is 321): DL-319 to DL-322 (emit rule), DL-320 to DL-323 (FrameSink never-drop routing). DL-318 is unchanged; #833's ids are load-bearing supersede pointers and stay put. Also annotates the frozen record header with the mapping (annotate-don't-rewrite house rule). Byte-identical to the ledger hunks already carried by #850 (RIG-2616 T2); landing it standalone on main unblocks the fleet ahead of the stack. Ledger-impact: renumber DL-319 to DL-322 (emit rule) and DL-320 to DL-323 (FrameSink never-drop routing); no new rows. Co-authored-by: Matt Wilkinson <matt@rigel.build>
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
2 participants
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.
Reverses the RIG-2542 client-only retirement: brings
mode="embedded"back to the native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode, and designs finishing it for macOS. Matt's 2026-09-01 ruling: support BOTH podman and microVM runners going forward, so embedded mode returns and gets finished for macOS.The retirement's premise is falsified. The client-only epic (DL-235) was driven by one upstream constraint — the container Runner being dropped once the microVM Runner lands, which requires a KVM floor. Keeping both runners makes rootless podman a permanent supported tier for single-tenant deployments, so the KVM-gating that retired embedded is gone and the retirement reverses cleanly: the supervisor design was never unbuilt (DL-108 stayed Active), only the app's invocation of it was deleted.
Client mode survives whole. This removes the word "only" from the client-only thesis, not the client. The client surface stays first-class and is the recommended steady-state for a real self-host deployment (always-on stack on a VPS/EC2, app connects over TLS) and the only mode for the managed multi-tenant deployment.
Topology — three funnel entries, two independent axes
The record separates the app mode (embedded vs client — this record's concern) from the runner backend (podman vs microVM — compass-obs's #804 concern, consumed here), and records the recommended backend per entry:
/dev/kvm). microVM is usable where the host has KVM (raw Linux); WSL2 has no KVM out of the box, so podman there too. App mode: embedded (the app spawns/supervises a local stack). Onboarding + local dev, zero-config. NOT the production steady-state.compass-stack up. The suggested self-host steady-state; the built T5 surface unchanged.The security boundary follows the trust model, not deployment uniformly (DL-318, compass-obs PR #804): a runtime isolating untrusted multi-tenant code needs the hardware boundary; a single-tenant box running the operator's own code has no untrusted tenant, so rootless podman is a correct boundary — a permanent tier needing no
/dev/kvm, with microVM recommended where KVM exists. An OSS-core scope note keeps the managed deployment's product-strategy specifics out of this repo.Ledger delta (this PR)
New rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres). Status flips: DL-235 → superseded by DL-319, DL-237 → DL-320, DL-238 → DL-321. DL-236 and DL-259 stay Active (partial supersession recorded by citation in DL-319's cell, per the never-reword convention); DL-215/DL-217/DL-106 keep their existing status (mechanism/shape restored by citation, no resurrection edit). The record and its ledger links live under
docs/designs/ui/(RIG-3113/#832 dissolvedproduct/intoui/).Open Questions
Ten load-bearing OQs carry recommendations for Matt's gate: postgres-as-container for embedded; embedded-as-absent-app.toml-default with a first-run confirm;
--modeoverride restoration; Windows deferral; the #804 freeze-order dependency; the darwin AF_UNIX-over-virtiofs socket-topology gap; a podman-version FATAL preflight check (OQ-8); docker socket vs force-podman (OQ-9 — recommend force-podman: the--userns=keep-id:uid=isolation boundary is podman-specific and does not port to docker's daemon-global userns-remap); apple/container as a macOS backend (OQ-10 — recommend defer: macOS-26 + Apple-silicon-only, pre-1.0 with declared breaking changes; podman-machine reuses the existing adapter stack); embedded microVM on Linux (OQ-11 — recommend v1 container-only, follow-up). One non-load-bearing deferral (quit-anyway on failed teardown). Per the design skill, load-bearing OQs are resolved at Matt's freeze; the record designs against stated assumptions meanwhile.Review
Drafted by a
designsubagent, red-teamed by adesign-criticsubagent (12 findings, all folded), then driver-reviewed and run through the mandatoryreviewpass over three rounds (0 high / 0 medium at all-clear before Matt's earlier read): the podman-version preflight gap (medium) and two editorial lows were folded. Matt's freeze-gate feedback (topology matrix, OSS-core scope, the docker/apple-container/embedded-microVM forks) is folded here; a fresh review pass covers the new delta. #832 having merged mid-review dissolvedproduct/intoui/, forcing a full rebase — the PR is reconstructed as a single coherent design commit on theui/path (the rename made the prior per-commit interdiffs unlandable).Implementation is decomposed into per-task follow-ups filed after freeze.
Spec-impact: adds the embedded-mode revival design record (Draft) under
docs/designs/ui/.Ledger-impact: adds DL-319/320/321; flips DL-235/237/238 to superseded.
Refs RIG-3139, RIG-1662
Co-authored-by: Matt Wilkinson matt@rigel.build