Repository navigation
Split the pure core into its own crate - #33
Merged
Merged
Conversation
Closes #23. docs/SPEC.md calls the Engine pure and the primary test seam, and the source honoured that, but the crate did not: everything lived in one package depending on tauri and objc2, so cargo test linked the whole platform stack to run arithmetic and nothing would have failed if a future change imported Tauri into the Engine. crates/core holds what needs no window server: the Engine, Character Package loading, Memory, the overlay arithmetic, snapshot assembly, and the adapter traits with their fakes and their degraded-mode stubs. Its dependency tree is png and nothing else, checked in CI rather than trusted -- the Linux job now runs cargo tree, clippy and the core tests, which it could not do at all before. src-tauri keeps what does: main.rs, the Tauri setup, and one macos module holding every AppKit and CoreGraphics implementation. Each of those implements a trait the core declares, which is the shape the split makes enforceable. The move surfaced a gap the old layout hid. In a library a `pub` item counts as reachable, so nothing complained that the macOS activity source is never constructed. In a binary nothing is reachable, and the split turned that quiet gap into a compiler error. It is marked and attributed to #10 and #11 rather than deleted. Behaviour is unchanged: 78 tests as before, 76 of them now in a crate that builds anywhere, and scripts/verify-overlay.sh still passes on a two-display desktop -- the sprite falls, perches on a real window edge, follows it at 44ms, drops at 64ms when it closes, and never stands on the desktop's furniture. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two-axis code review of this branch found one hard defect on each axis. The shell stopped compiling off macOS. Renaming platform/ to macos/ took the `#[cfg(not(target_os = "macos"))] configure_overlay` stub with it, while main.rs kept calling it unconditionally, so on any other platform the module is empty and the call unresolved. docs/SPEC.md commits to that stub -- "the platform interface exists in v1 and Windows is stubbed" -- and CI never builds the shell on Linux, so nothing would have caught it. platform.rs is the seam again, owning both arms of both decisions; the macOS implementations live under it, and main.rs now has no cfg of its own. The purity guard could not see the way purity is most likely to break. `cargo tree` reads the host target, so on the Linux runner a dependency behind [target.'cfg(target_os = "macos")'.dependencies] -- exactly the form src-tauri already uses -- is invisible. Demonstrated by adding objc2 to the core that way: against a Linux target the old guard reports clean and --target all catches it. The guard now passes --target all and no longer swallows a cargo tree failure through `|| true`. Also from the review: docs/SPEC.md still said the layout was single-crate until #23 landed; the README advertised bare `cargo test` under "fast, pure, no windowing system", which at workspace root builds the shell too; the Linux job skipped cargo fmt, which compiles nothing and runs fine there; two moved doc comments still named the pre-workspace manifest path; and version, edition and licence are now declared once in [workspace.package]. 78 tests, clippy clean, and scripts/verify-overlay.sh passes 23 checks on a two-display desktop. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Raised in review of this PR: why are cargo fmt, clippy and swiftc skipped in the Linux pre-commit run, and why does the macOS job run cargo fmt and clippy by hand instead? Is pre-commit broken there? It is not. The macOS job simply never installed it, and the result was that cargo-fmt, cargo-clippy and swiftc-typecheck each existed twice: once in .pre-commit-config.yaml, which is what contributors run locally, and once as a hand-written step here. The two copies could drift, and for clippy and swiftc the hook copy never ran in CI at all -- skipped on Linux, absent on macOS -- so editing their arguments in the hook config would have changed nothing that gates a pull request. The macOS job now runs those two hooks from the same config, one invocation each because pre-commit takes a single hook id. No check is restated in this file. Verified: all 22 hooks run somewhere, none runs twice. cargo fmt is no longer repeated on macOS. Formatting does not vary by platform and the Linux job already runs the hook. The jobs are renamed for what they are. The split is by capability rather than by language -- `checks` runs everything that needs no macOS toolchain, including the portable core crate, and `macos` runs the rest -- so calling them lint and rust obscured why any of it is arranged this way. main is unprotected, so no required check names break. The core-crate step stays a hand-written step deliberately. It is not a duplicate of the clippy hook: it builds and tests ai-buddy-core alone on Linux, which is the property the split exists to guarantee and which no hook expresses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Raised in review: SKIP in the workflow is ugly, is the linting really macOS-specific, and can pre-commit condition on the platform natively? It cannot. pre-commit accepts files, types, stages, language and a dozen more, and nothing for os or arch. So the condition has to live somewhere, and the workflow was the wrong somewhere: a contributor running the hooks on Linux got a compile failure with no explanation, because the reason lived in a file they were not reading. Only one of the two hooks was ever genuinely macOS-specific. swiftc ships with Xcode, so no restructuring makes it portable. cargo clippy was macOS-bound only because it linted the whole workspace, and since the crate split the core lints anywhere -- it depends on png and nothing else. It is now two hooks: cargo-clippy-core, which runs everywhere including a Linux laptop, and cargo-clippy-shell, which does not. That is new coverage rather than a rename. Both macOS-only hooks now test uname themselves and exit cleanly with a one-line reason. So both CI jobs run the same command -- `pre-commit run --all-files` -- and neither has to know which hooks are platform-bound. The Rust install moved ahead of pre-commit, which now needs a toolchain on Linux too. The core-crate step drops its clippy line, which the new hook covers, and keeps `cargo tree --target all` and the core test run, which no hook expresses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The previous commit had both jobs run `pre-commit run --all-files` on the theory that the self-skipping guards made the jobs interchangeable. CI disagreed: the macOS runner has no shfmt and no shellcheck, because only the Linux job installs them, and running every hook there meant needing every hook's tooling. Installing them on macOS would have fixed it by paying twice for work Linux already did. The macOS job runs the two hooks by id instead. The guards stay, and they are not redundant with this list. The guard exists for a contributor running the hooks on Linux, who otherwise gets a compile error with no explanation. The list exists so CI does not redo the portable half on the slower runner. Different readers, both worth serving. SKIP is still gone, which was the point. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Raised in review: why does cargo test run only on macOS? It does not, and the step name was hiding that. The Linux job has been running all 76 core tests inside a step called "Core crate builds and passes with no platform binding", which reads like a dependency check. The macOS run adds exactly two tests, the shell's, which cannot compile on Linux at all. That step is now two, each named for what it does: one asserts the core reaches no platform binding, the other runs the core's tests and says why doing so on Linux is not redundant. The core is float-heavy coordinate arithmetic and ubuntu-latest is x86_64 while macos-latest is arm64, so this is the only place it runs on a second architecture. Checking that turned up a real gap. `cargo test --all-targets` excludes doctests -- three test suites become two -- so both jobs were skipping them silently. There are none today, which is exactly why nobody would have noticed the first one being ignored. Demonstrated with a doctest asserting 2 + 2 == 5: --all-targets reports 76 passed and --doc fails. Both jobs now run --all-targets and --doc. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Raised in review: why is the comprehensive testing macOS-only, and should lint and test be a matrix? They should. The shell was built on macOS alone because it is a Tauri app and Tauri needs GTK and WebKit headers on Linux, but that is an apt install, not an impossibility. Nothing here is macOS-only at the source level: platform.rs carries a non-macOS arm for every decision, and the core is portable by construction. The cost of not doing this is already on record. A review of this branch found that the non-macOS arm had silently rotted -- main.rs called configure_overlay unconditionally while the module was gated away -- and nothing caught it, because the shell was never compiled anywhere that would notice. Building it on Linux closes that. One job over [ubuntu-latest, macos-latest]. Both run the same hooks, the same purity assertion and the same tests; only tool installation differs, and the two hooks that need macOS already guard themselves on uname. fail-fast is off, since telling the platforms apart is the point. This also gets the full suite onto two architectures rather than the core alone: ubuntu-latest is x86_64 and macos-latest is arm64, and the coordinate code is float-heavy. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adopts the method now on omesser/ai-goodies: parse the releases API with jq rather than a regex, and track the latest release rather than a pinned version. Adapted in one way. ai-goodies hardcodes _linux_amd64 because it runs on Linux only; this workflow is a matrix, so the asset comes from uname -s and uname -m. A runner changing architecture then picks the right binary instead of silently fetching the wrong one, and an unknown pair fails loudly rather than downloading nothing. Verified against the live API: each selector matches exactly one asset, and curl -f still means a failed download errors instead of leaving an HTML error page on disk marked executable. Dropping the pin is the maintainer's call and reverses my earlier reasoning, so the risk is worth writing down: CI now tracks latest while contributors run whatever their package manager gives them, and a release that formats differently fails a pull request that changed no shell at all. Checked today rather than assumed -- latest has moved to v3.14.0 while this machine has v3.13.1, and both format scripts/verify-overlay.sh byte for byte identically. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 28, 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
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.
Closes #23.
What changed
A workspace with two crates.
crates/core— depends onpng, nothing elsesrc-tauri— depends on Tauri and objc2main.rs, the Tauri setupplatform.rs— the seam that picks an implementationplatform/macos/— AppKit and CoreGraphicsEach file under
platform/macos/implements a trait the core declares. That iswhat makes the boundary enforceable rather than aspirational.
Why
docs/SPEC.mdcalls the Engine "pure, synchronous, no I/O" and the primary testseam. The source honoured it; the crate did not. One package depending on
tauriand
objc2meantcargo testlinked the whole platform stack to run arithmetic,the Rust checks could not run on Linux at all, and nothing would have failed if
a change imported Tauri into the Engine.
Purity is a build property now. The
checksjob runs on Linux:--target allmatters.cargo treereads the host target, so on Linux adependency behind
[target.'cfg(target_os = "macos")'.dependencies]— the formsrc-taurialready uses — is invisible. Addingobjc2to the core that way andchecking against a Linux target: the host-only guard reports clean,
--target allcatches it.How to verify
Commands lost their
--manifest-path; a workspace needs none.What the move surfaced
A gap the old layout hid. In a library a
pubitem counts as reachable, sonothing complained that
MacosActivitySourceis never constructed. In a binarynothing is, and the same code became a compiler error. Marked and attributed to
#10 and #11 rather than deleted — the Director is its first consumer.
The stubs now compile.
StubWindowSourceandStubActivitySourcewere deadon macOS-only CI. The Linux job builds them, so the "Wayland degrades to
screen-edge physics" path is checked rather than assumed.
Review findings, fixed
A two-axis review found one hard defect per axis, both since fixed:
platform/tomacos/took the
#[cfg(not(target_os = "macos"))] configure_overlaystub with itwhile
main.rskept calling it unconditionally.platform.rsis the seamagain, owning both arms of both decisions.
--target allfix above.
Also corrected: the
docs/SPEC.mdparagraph still saying the layout wassingle-crate until #23 landed; the README advertising bare
cargo testunder"fast, pure, no windowing system", which at workspace root builds the shell too;
the Linux job skipping
cargo fmt, which compiles nothing; two stale doccomments; and package metadata now declared once in
[workspace.package].CI, after review
One job, matrixed over
ubuntu-latestandmacos-latest. Both run the samehooks, the same purity assertion and the same tests. Only tool installation
differs, and
fail-fastis off so one platform failing still reports the other.The whole workspace is now built and tested on Linux too, not macOS alone. The
shell is a Tauri app, so Linux needs GTK and WebKit headers — an
aptinstall,not an impossibility. Nothing here is macOS-only at the source level:
platform.rscarries a non-macOS arm for every decision.That matters because of what the review of this branch found: the non-macOS arm
had silently rotted —
main.rscalledconfigure_overlayunconditionally whilethe module was gated away — and nothing caught it, because the shell was never
compiled anywhere that would notice. Now it is.
ubuntu-latest(x86_64)cfg'd outmacos-latest(arm64)The core running on both is deliberate: it is float-heavy coordinate arithmetic,
and this is the only way it sees a second architecture.
No
SKIPlist. pre-commit has no platform key — the schema acceptsfiles,types,stages,languageand a dozen more, nothing for OS or arch. So thecondition lives in the hooks: the two that need macOS test
unamethemselves andexit cleanly elsewhere with a reason. A
SKIPin the workflow would hide thatfrom anyone running the hooks locally.
Only one hook was ever genuinely macOS-specific.
swiftcships with Xcode.cargo clippywas macOS-bound only because it linted the whole workspace, andsince this split the core lints anywhere — so it is now
cargo-clippy-core,which runs everywhere, and
cargo-clippy-shell, which does not.Both platforms run
--all-targetsand--doc.--all-targetsexcludesdoctests, so both were skipping them silently; demonstrated with a doctest
asserting
2 + 2 == 5, which--all-targetsreports as 76 passed and--docfails.
Every check has one definition, in
.pre-commit-config.yaml. The workflowrestates none of them.
Known and deferred
.gitignorekeeps/src-tauri/target/alongside/target/. An older checkoutstill carries the old directory, and without both lines it stops being ignored
— which staged 1.7GB of build output the first time.
cargo clippyhook, which covers thewhole workspace including the shell. The core is checked on its own above.
docs/SPEC.mdstill describesMemoryManifestas an adapter trait while thecode is a concrete struct. Unrelated, still open.
🤖 Generated with Claude Code