docs(lemonade): repo deep-dive + ADR/plan tightenings from research#138
Merged
Merged
Conversation
Lands the upstream-codebase research handoff that resolved several open questions on ADR-0006, plus the ADR + migration-plan tightenings those answers produced. ## What lands - `docs/internal/lemonade-repo-deep-dive-2026-05-22.md` (276L) — read of `lemonade-sdk/lemonade@7af26f75` (HEAD of main, 2026-05-21): dev internals, full API surface, embeddable build, omni recipe, WS protocol. The "what's actually in there" companion to the spike's "what happens when we run it" findings. ## ADR-0006 tightenings (from deep-dive) - §3 (Drive method): "HTTP-first with CLI fallback" → "HTTP only". The spike's `/v1/load` "type must be string but is null" failure was a malformed body (nlohmann::json[] throws on null access), not a missing field. CLI fallback isn't needed. - §3 (Schema): documents that only `model_name` is required for `/v1/load`; everything else is optional. - §5/§6 (Process supervision + bundling): "containerised lemond" → "AMD's embeddable tarball + bare systemd unit". Lemonade ships an `embeddable` cmake target producing a portable lemond+lemonade tarball — that's the official redistributable artifact. Building a container around it duplicates AMD's work and reintroduces the docker-build apparmor pain hal0 has on LXC. ## migration-plan tightenings - Decision #7 (Bundling+pin): `{image, digest, version}` → `{tarball_url, sha256, version}` to match the embeddable distribution. - Decision #11 (Drive method): mirrors ADR §3 — HTTP-only with the resolved schema, no CLI bootstrap fallback. ## Why a separate PR from #137 (the client skeleton) PR #137 already implements what these docs describe — keeping the docs/code split on a per-PR basis makes the migration story easier to read in `git log`: "client conforms to ADR-0006 §3 (HTTP-only)" reads cleanly because the ADR §3 it conforms to is the post-tightening version, landed alongside. Co-Authored-By: Claude Opus 4.7 (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.
Summary
Lands the upstream-codebase research handoff that resolved several open questions on ADR-0006, plus the ADR + migration-plan tightenings those answers produced.
Conforms with
PR #137 (`LemonadeClient` skeleton) already implements the post-tightening shape — these docs make the "client conforms to ADR §3" line accurate in `git log`.
🤖 Generated with Claude Code