docs: ADR-037 Native App Framework (Proposed)#6
Merged
Conversation
Proposes the layered userspace app framework (the prioritized #3 direction): - L0 `libsys-rt` — runtime: #[service_main] entry macro, panic handler, allocator - L1 `libipc` — typed IPC stdlib: Message + ServiceError/Result + ServiceLoop<Handler> - L2 `libui` — GUI toolkit (widgets/layout/event loop libgui v0 deferred) - L3 `cambios-pkg`— signed manifest/package, handed to ADR-018 (already owns the manifest) MVP = L0 + L1 core; zero new kernel syscalls (verification-neutral). First consumer = rewrite policy-service (prove before greenfield). Grounded in the scoping run: 23 services / ~12k LOC repeat ~10 boilerplate areas (333 marshalling sites, 11 reinvented status sets, 24 duplicate linker scripts) — est. 10-15x per-service reduction. Extends libsys/libgui, does not replace them; all of L0-L2 is pure userspace (push cycles out of the kernel ring). Status: Proposed. Two OPEN DECISIONS flagged for sign-off: 1. Framework license — MPL-2.0 (by libsys precedent; apps free to pick their license) vs AGPL-3.0-or-later (whole-userspace copyleft). Draft default MPL; values call. 2. ADR scope — L0-L2 here + L3 to ADR-018 (recommended) vs one ADR for all four layers. Allocated via `make new-adr` (8a01c8a) — the first ADR numbered through the tool rather than by eyeballing max+1 (the failure that nearly produced a duplicate ADR-036). Staged files: docs/adr/037-native-app-framework.md docs/adr/INDEX.md Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…R-018 boundary
Review feedback (ADR-037 vs ADR-018):
- L3 is NOT a manifest/package format. ADR-018 owns the signed manifest, its wire
format, signing, and the kernel reservation table. L3 narrowed to authoring
ergonomics: the canonical link.ld (replacing 24 dupes) + a service-crate template.
Title: "package layering" -> "service scaffolding".
- Phase-2 endpoint registry reframed as the build-time SOURCE artifact that
tools/build-manifest (ADR-018 step 2) consumes — unidirectional, convergence
direction determined, never a parallel or runtime authority.
- Boilerplate claim is now measured (write user/init twice: raw libsys vs framework,
report the delta) rather than a speculative 10-15x — init is a real not-yet-written
target, so the "raw" baseline is not a strawman.
- License settled: L0-L2 MPL-2.0 (libsys precedent, linkable surface); L3 permissive
(Apache-2.0/CC0 — copied-from, not linked-into; a distinct question). Scope agreed.
- Verification posture stated: L0-L3 are outside the kernel verification target
(matching ADR-018's init stance); host-test bar = libgui (26 / 13 / 8).
- #[service_main] is a macro_rules! macro (no syn/quote). L0-L2 are kernel-ABI-neutral
and land in any order vs ADR-018 steps 1-7. webmin/drainer portal marked a candidate
consumer (one-line definition), not a standing placeholder.
- Added a "Relationship to ADR-018" boundary table.
Staged files:
docs/adr/037-native-app-framework.md
docs/adr/INDEX.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The CI baseline-lints gate (check-deferrals) flagged 2 deferral tokens in the
ADR-037 draft without an adjacent observable trigger:
- L1 Encode/Decode derive: now "held back. Revisit when: a second real
request/response struct needs it" — an explicit Convention-9 trigger.
- L2: "libgui v0 deferred" -> "the tier that libgui v0 left out" — describes
libgui's existing scope, removing the trigger-less token.
No decision/content change; the lint correctly caught the draft's prose (the
guardrail working on agent output, including the ADR-drafting agent).
Staged files:
docs/adr/037-native-app-framework.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Drafts ADR-037 (Proposed) for the native app framework - the prioritized #3 direction. Allocated via the new
make new-adr(first ADR numbered the safe way, not by eyeballing max+1).The proposal: a layered framework that extends libsys/libgui (replaces neither):
libsys-rt- the_start/panic/allocator ritual all 23 services hand-rolllibipc- typed IPC stdlib (Message+ServiceError/Result+ServiceLoop<Handler>), collapsing 333 marshalling sites + 11 reinvented status setslibui- the widgets/layout/event-loop tier libgui v0 deferredcambios-pkg- signed manifest/package, handed to ADR-018 (which already owns the boot manifest)MVP = L0 + L1 core, zero new kernel syscalls (verification-neutral). First consumer = rewrite
policy-service(prove before greenfield). Grounded in the scoping run: ~10-15x per-service boilerplate reduction.Two open decisions need your sign-off (it's why this is Proposed, not Accepted):
The ADR defines the L0-L3 terms inline (no reliance on outside context) and lays out phasing + the speculative-design/sawtooth/verification risks.
Touches
docs/adr/(owned) -> needs your code-owner review. Review is also where you make the two calls above.🤖 Generated with Claude Code