Skip to content

Split the pure core into its own crate - #33

Merged
omesser merged 8 commits into
mainfrom
feat/23-core-crate
Aug 28, 2026
Merged

omesser merged 8 commits into
mainfrom
feat/23-core-crate

Conversation

@omesser

@omesser omesser commented Aug 28, 2026 •

Copy link
Copy Markdown
Owner

Closes #23.

What changed

A workspace with two crates.

crates/core — depends on png, nothing else src-tauri — depends on Tauri and objc2
Engine, Character Package loading, Memory main.rs, the Tauri setup
overlay arithmetic, snapshot assembly platform.rs — the seam that picks an implementation
the adapter traits, their fakes, the degraded-mode stubs platform/macos/ — AppKit and CoreGraphics

Each file under platform/macos/ implements a trait the core declares. That is
what makes the boundary enforceable rather than aspirational.

Why

docs/SPEC.md calls the Engine "pure, synchronous, no I/O" and the primary test
seam. The source honoured it; the crate did not. One package depending on tauri
and objc2 meant cargo test linked 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 checks job runs on Linux:

cargo tree -p ai-buddy-core --target all   # must show no tauri, no objc2
cargo clippy -p ai-buddy-core --all-targets -- -D warnings
cargo test -p ai-buddy-core

--target all matters. cargo tree reads the host target, so on Linux a
dependency behind [target.'cfg(target_os = "macos")'.dependencies] — the form
src-tauri already uses — is invisible. Adding objc2 to the core that way and
checking against a Linux target: the host-only guard reports clean, --target all catches it.

How to verify

cargo test                                  # 78, unchanged
cargo clippy --all-targets -- -D warnings
scripts/verify-overlay.sh                   # 23 checks, needs a desktop

Commands lost their --manifest-path; a workspace needs none.

What the move surfaced

A gap the old layout hid. In a library a pub item counts as reachable, so
nothing complained that MacosActivitySource is never constructed. In a binary
nothing 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. StubWindowSource and StubActivitySource were dead
on 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:

  • 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. platform.rs is the seam
    again, owning both arms of both decisions.
  • The purity guard had a hole on the runner it runs on — the --target all
    fix above.

Also corrected: the docs/SPEC.md paragraph still saying the layout was
single-crate until #23 landed; the README advertising bare cargo test under
"fast, pure, no windowing system", which at workspace root builds the shell too;
the Linux job skipping cargo fmt, which compiles nothing; two stale doc
comments; and package metadata now declared once in [workspace.package].

CI, after review

One job, matrixed over ubuntu-latest and macos-latest. Both run the same
hooks, the same purity assertion and the same tests. Only tool installation
differs, and fail-fast is 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 apt install,
not an impossibility. Nothing here is macOS-only at the source level:
platform.rs carries 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.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. Now it is.

core tests shell tests
ubuntu-latest (x86_64) 76 0 — its tests cover AppKit and are cfg'd out
macos-latest (arm64) 76 2, plus 2 ignored live-desktop checks

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 SKIP list. pre-commit has no platform key — the schema accepts files,
types, stages, language and a dozen more, nothing for OS or arch. So the
condition lives in the hooks: the two that need macOS test uname themselves and
exit cleanly elsewhere with a reason. A SKIP in the workflow would hide that
from anyone running the hooks locally.

Only one hook was ever genuinely macOS-specific. swiftc ships with Xcode.
cargo clippy was macOS-bound only because it linted the whole workspace, and
since 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-targets and --doc. --all-targets excludes
doctests, so both were skipping them silently; demonstrated with a doctest
asserting 2 + 2 == 5, which --all-targets reports as 76 passed and --doc
fails.

Every check has one definition, in .pre-commit-config.yaml. The workflow
restates none of them.

Known and deferred

  • .gitignore keeps /src-tauri/target/ alongside /target/. An older checkout
    still carries the old directory, and without both lines it stops being ignored
    — which staged 1.7GB of build output the first time.
  • The Linux job still skips the shared cargo clippy hook, which covers the
    whole workspace including the shell. The core is checked on its own above.
  • docs/SPEC.md still describes MemoryManifest as an adapter trait while the
    code is a concrete struct. Unrelated, still open.

🤖 Generated with Claude Code

omesser and others added 8 commits August 28, 2026 23:12
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>
@omesser
omesser merged commit 884a18d into main Aug 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Split the pure core into its own crate

1 participant