Solipsist

A native macOS harness for Boris, the deterministic Zig graph-native publication compiler.

Radio UserLand’s job in Mail’s body: sources in Settings, mailboxes on the left, a reading place in the middle, inspector drawer on the right. Preview and the Svelte editor are companion windows we host. We do not invent a second compiler.

Status: M0–M17 landed — Mail body (#98), clone, graph folders, watch contract, GitHub source + write verbs, Pull Requests mailbox — plus post-ship polish: accessibility (#239–#243), editor/compose depth, live sidebar. Notarized release is parked on a paid Apple Developer ID; #110/#111 closed not-planned — unpark steps in #110. File → Open… a folder under Stunts/ (start with happy/). make test decodes checked-in fixtures (no boris binary).

Start here

• New human? Read docs/ONBOARDING.md — the 30-minute path through the repo.
• Agent? Read AGENTS.md, then docs/ROADMAP.md and docs/HARNESS.md.
• Run make doctor to check your environment and repo hygiene.

Layout

Sources/
  App/        app lifecycle, coordinator, settings, commands, help
  Chrome/     main window chrome: sidebar, reading host, inspector drawer
  Workspace/  sources (local / git / GitHub), sidebar state, persistence
  Play/       mailbox surfaces: pages, outputs, publish, plan, activity
  Inspector/  drawer content: profile/page fields, theme browser
  Companions/ hosted foreign surfaces: Preview (watch --serve), Editor
  Compose/    native editor window: buffer, highlight, Oliver preview
  Intents/    App Intents — Siri drafts (M18)
  Models/     Codable mirrors of Boris JSON contracts
  Engine/     locate, run, actor — the only Process owner
  Security/   stdin secret buffers, Keychain, credential helpers
Spike/        M1 CLI spike (`make run-spike`)
scripts/      embed-boris.sh, doctor.sh, stunt-smoke.sh, …
Stunts/       dogfood corpora (happy, broken-*, cook-one)
Tests/        Contract decode tests and JSON fixtures
vendor/boris-agent-kit/   pin only (no binaries)
site/         public docs site — itself a Boris publication
brand/        project graphics: icon, banner, palette
docs/         ROADMAP · HARNESS · MISSION · cards · issues · ONBOARDING

Never commit SUPPORT-NOT-FOR-GITHUB/ or engine binaries.

Prerequisites

• Solipsist app: macOS 27+ (arm64 + x86_64)
• Spike harness and contract tests (make run-spike / make test): macOS 26+
• Xcode 26+ (tested Xcode 27 / Swift 6)
• Zig 0.16+ only if you must rebuild the engine
• XcodeGen is vendored into .tools/ by make tools

Commands

make tools
make generate
make build
make test
SOLIPSIST_BORIS_BIN=/path/to/boris make run-spike

The spike chooses an impact page from the returned graph. To select one, pass SPIKE_CONTENT=/path/to/content SPIKE_PAGE=guides/getting-started. make test-spike runs disposable-corpus CLI regressions with a stub engine, including missing reports and early watch exits.

Engine search order: SOLIPSIST_BORIS_BIN → app bundle → SUPPORT-NOT-FOR-GITHUB/…/bin/boris (local only) → ../boris/zig-out/bin/boris.

Stunts & Contract Testing

Solipsist includes a suite of test corpora under Stunts/:

• happy/: Valid 3-page publication.
• broken-frontmatter/: Invalid YAML frontmatter (EFRONTMATTER).
• broken-parent/: Missing trunk/parent node (EPARENTMISSING).
• broken-duplicate-id/: Duplicate page IDs (EDUPLICATEID).
• broken-wikilink/: Unresolved wikilink references (EREFERENCEMISSING).
• cook-one/: Recipe markup in Cooklang format.

Run make test to execute contract decoding tests against checked-in fixtures, or run scripts/stunt-smoke.sh to smoke test against a live Boris engine.

CI

PRs to main run GitHub Actions (spike against a pin-built boris, app compile, fixtures contract tests, and lint). The app job still sets SKIP_EMBED_BORIS=1 — no engine binary is vendored. A fart job is reserved and disabled.

Boundaries

• Never touch the boris repo from here. File issues; vendor the binary.
• Never reimplement Boris semantics in Swift.
• Never swallow diagnostics or exit codes.
• Subprocess isolation is a feature.