[drew]

Summary

Propose splitting OpenShell into a smaller core and focused repositories so new maintainers can own platforms, packaging, SDKs, and provider integrations. Keep RFC 0019 short and conversational for early discussion.

Related Issue

Closes #4425

Changes

• Define the proposed repository responsibilities and ownership expectations.
• Outline an incremental migration, risks, and alternatives.
• Leave macOS isolation, microVM placement, host process assembly, and cross-repository compatibility as open questions.

Testing

• Markdown lint passes (mise exec -- markdownlint-cli2 rfc/0019-repository-migration/README.md).
• git diff --check passes.
• Unit and E2E tests are not applicable to this RFC-only change.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture documentation updates are not applicable to this draft proposal.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[politerealism]

Simon pointed me here from #3510 (Fedora packaging), so a few notes from that work on where the packaging line might fall. Take these as ideas.

It might help to separate two kinds of packaging, because they couple to core very differently:

• Repackaging published binaries (what openshell.spec does today via OPENSHELL_PREBUILT_BINARIES_DIR, and what install.sh does). This is loosely coupled to core: it needs a tag and the release artifacts.
• Building from source in a distro's infrastructure (Fedora's Koji builds offline from source). This is tightly coupled. feat: package OpenShell for Fedora #3510 found several build-time contracts that currently live in core: the Rust toolchain pin and vendored dependencies, whether the build honors PROTOC instead of the bundled compiler (fix(build): honor PROTOC when generating protobuf code #4441), the Python proto stub generation (fix(rpm): build the Python SDK from older protoc and install every SDK module #4439), the Z3 bindings tied to z3-sys (feat: unbundle Z3 from gateway runtime packaging #1969), and static-PIE linking for the supervisor and sandbox binaries.

Oliver raised the lockstep concern on #4244: distro packaging needs build flags, dependencies and toolchain versions kept in sync with core. One way to keep a separate packages repo honest might be for core to document a small source-build contract (supported features, environment variables, minimum toolchain, expected outputs) and to run a cheap from-source smoke build in its own CI, so drift shows up in core before it reaches a packaging repo. That could also keep the option open of leaving the from-source recipes with core while openshell-packages owns publishing and installation.

[drew]

One way to keep a separate packages repo honest might be for core to document a small source-build contract (supported features, environment variables, minimum toolchain, expected outputs)

That makes sense to me. Are there other examples of projects doing this?

[...] and to run a cheap from-source smoke build in its own CI, so drift shows up in core before it reaches a packaging repo

Hopefully we could use the same build recipe for the core and the package repos, so core would always be the source of truth from a build recipe perspective.

[politerealism]

Some examples, and what a contract looked like for OpenShell.

Other projects write down what distro packagers need, usually as a section in their build docs. I checked three:

• Zed has a "Notes for packaging Zed" section (docs/src/development/linux.md). It lists which crates to build, where each binary goes, the desktop file template, the environment variable that turns off auto-update, and points at script/bundle-linux as a complete example build.
• Node.js has "Building to use shared dependencies at runtime" in BUILDING.md: configure options such as --shared-openssl for distributions that manage their own dependencies, and a note that the distribution must keep those libraries matching what the binary expects.
• Neovim has "Build without 'bundled' dependencies" in BUILD.md, with USE_BUNDLED switches, and points packagers at the Debian package and Homebrew formula for the exact versions.

I only read the docs. I didn't check whether any of them also run a from-source build in CI, so I can't say how they keep the docs from drifting.

I agree about one recipe with core as the source of truth. For a Fedora build, I think it would be the cargo invocation and its inputs, not the whole spec, because Fedora builds offline from vendored sources and can't use prebuilt binaries. Building 0.1.6 for Fedora, these were the differences I carried:

• the workspace version is 0.0.0 and is stamped at release time, so the spec patches it
• sqlx's sqlite feature compiles SQLite into the gateway; a spec patch switches it to sqlite-unbundled so it links the system library
• PROTOC and the Python proto stubs needed changes (fix(build): honor PROTOC when generating protobuf code #4441, fix(rpm): build the Python SDK from older protoc and install every SDK module #4439, both merged)
• Z3 links the system library instead of the vendored one
• the prover has no man page

A short contract in core would cover the same things: supported features, the environment variables the build honors, the minimum toolchain and the expected outputs. If the SQLite choice and the version stamp became a feature flag and an environment variable, the Fedora spec would need almost no patches. I can write that down in more detail if it would help the RFC.

[ericcurtin]

Keep in mind, docker/podman and systemd-nspawn have a lot of overlap.

docker/podman are generally more mature versions of systemd-nspawn, more engineering effort put in.

Not against adding it, but it's effectively scoping in a less mature version of docker/podman.

[rhuss]

The Go SDK is the first RFC 0019 move through the cutover: its history and a standalone module are in ai-openshell/sdk-go, and #5245 deprecated sdk/go in core and dropped its CI gate. The move isn't finished yet: the release automation is waiting for its GitHub App, and removing sdk/go from core comes after the next stable release. I collected the lessons so far and a per-phase checklist for the next moves in #5273.

Three of them relate to the implementation plan here:

1. Retire in two core PRs. The first deprecates the old path and drops the CI gate; the second removes the code after a core release has shipped the deprecation and the new repository's automation is live. That's one concrete way to "validate the replacement before retiring its old paths".
2. Enforce the freeze with a check. A freeze announced in comments doesn't stop merges. chore(sdk/go): deprecate the in-tree Go SDK and drop its CI gate #5245 added a required check that fails on changes to the moved directory, together with dropping the gate that forced those changes.
3. Name at least two maintainers besides the person doing the move. The ai-openshell rulesets require last-push approval, so a team with only one other reviewer can't merge without an org admin.

On how the move runs: I drive it as spec-driven development with spec-kit and cc-spex, so there's a spec, a plan, and a phased task list, and every executed step goes into a migration log with its deviations from the plan. The discussion is long, but that's on purpose: it's meant to be fed to an agent planning the next move, so it walks around the traps we hit. At the end, the playbook becomes a migrate-repo agent skill that runs a migration as gated stages (intake, drain and freeze, import, port, automation, retire) with the history, verification, and porting scripts bundled, without needing spec-kit.

Feedback on the playbook is welcome in the discussion, so this thread can stay about the RFC.