Decision needed: where does the Desktop Git runtime come from after we remove bundled Git?

[Astro-Han]

Problem

Every Maka Desktop artifact ships a Git executable. apps/desktop/electron-builder.config.mjs copies node_modules/dugite/git into extraResources, about 141 MB of Git distribution.

Git is GPLv2, which is Category X under ASF third-party licence policy. The artifact currently carries resources/licenses/git/SOURCE_OFFER.txt (added in #2235). That satisfies GPLv2's written-offer obligation, but it does not make Category X material distributable by the ASF, and DISCLAIMER-WIP cannot waive it.

Dugite itself is MIT. The problem is the Git distribution it vendors, not the npm package.

This blocks G9 in the first-release tracker (#2974, implementation in #3276). It is currently the longest open path there, and no issue tracks the removal yet. Maka Desktop cannot be published as an ASF convenience binary until this is resolved.

What any replacement has to preserve

packages/runtime-host/src/server/bundled-git-runtime.ts does more than locate a binary. It verifies a maka_bundled_git_runtime_v1 manifest, checks platform and arch, resolves realpath, rejects symlinks and out-of-root paths, compares executableSha256, and derives a runtimeIdentitySha256. packages/storage/src/git-workspace-service.ts consumes that verified identity for owner-bound managed workspaces (#1742, #2129).

So a replacement has to keep:

1. A verifiable Git identity. Owner binding depends on runtimeIdentitySha256, which today comes from a manifest the build produces.
2. A known Git version. Behaviour is asserted against it in bundled-git-workspace-smoke.test.ts.
3. Diagnosable failure modes. The existing BundledGitRuntimeError codes reach users.

The good news is that distribution.kind ('dugite_native_v1') and the manifest provider field are already the seam for this. Adding a distribution kind is an extension, not a rewrite.

Options

A. Require Git on the user's machine. Resolve from PATH. Smallest change, smallest artifact. Cost: no hermetic guarantee, no trustworthy executableSha256, version drift across users, and first-run failure for the many Windows users without Git. The owner-binding identity would need a redesign.

B. Fetch the Git runtime on first use, outside the release artifact. Keep the manifest, the verification, and the distribution.kind model as they are; verify after download instead of after unpacking. All three constraints survive and the artifact carries no Category X material. Cost: first run needs network access, offline and air-gapped installs degrade, and we would have to decide on a download host. Whether an unbundled runtime download is acceptable under ASF policy is exactly what we need mentor and Legal guidance on — we are not assuming it is.

C. Replace Git with a non-GPL implementation. gitoxide is Apache-2.0/MIT and removes the problem at the root, but its feature coverage would have to be checked against what managed workspaces actually call. libgit2 is GPLv2 with a linking exception; we would rather have its ASF status confirmed than assume it. Cost: the largest engineering effort here, with possible behaviour changes in managed workspaces.

D. Reduce managed-workspace scope for the first release. Ship Desktop without the features that need a Git runtime and restore them later. Cost: user-visible capability loss, and it needs a product decision about what Desktop is without managed workspaces.

These are not mutually exclusive. B as the near-term path with C as the direction seems plausible to us, but we would rather hear that judged than assert it.

What we are asking

• Mentors and IPMC: is option B — shipping no Git in the artifact and fetching a verified runtime on first use — acceptable under ASF policy? If it is not, B is out and the choice narrows to C or D.
• Mentors and Legal: does libgit2's GPLv2 linking exception change its Category X status for a bundled desktop application?
• @zhiiw, as the author of Add an isolated managed Git workspace service #1742, Bundle and verify a hermetic Git runtime for managed workspaces #2199 and Publish source materials for the bundled Git runtime #2235: does the owner-binding identity model survive each of these options, and is there a constraint above that we have stated wrongly?

Anyone with experience shipping a Git-dependent desktop application under ASF policy — we would like to hear how you solved this.

References

• ASF third-party licence policy
• Tracker [TRACKING] First Apache Maka (Incubating) release #2974, G9 implementation release: publish ASF-compliant Desktop convenience artifacts #3276
• Bundled Git history: Add an isolated managed Git workspace service #1742, Bundle and verify a hermetic Git runtime for managed workspaces #2199, Publish source materials for the bundled Git runtime #2235, Gate managed workspace reads behind owner-bound Runtime Host execution #2129

---

This analysis was prepared with Claude Code against current main and must be reviewed by a human contributor of record. Licensing conclusions remain with the PPMC, mentors, and ASF Legal Affairs.

[zhiiw]

Thanks for raising this. The near-term implementation plan will be:

1. Remove bundled Git from ASF Desktop convenience artifacts. We will treat the delivery of a Git runtime as an implementation detail rather than a baseline release requirement. Until a verified replacement exists, managed-workspace functionality will be reported as unavailable before admission/T1; there will be no silent fallback after a durable mode has been selected.
2. Do not pursue first-use Git downloading for now. The ASF policy question remains useful, but we will not make the first release or the next engineering slice depend on that answer.
3. Run a time-boxed gitoxide feasibility effort. gitoxide is Apache-2.0/MIT and is a promising fit for Maka's local-only needs. We will evaluate it through a Maka-owned Rust helper/library boundary rather than depending on the explicitly unstable gix CLI. The spike must prove object/tree/commit handling, ref CAS, deterministic materialization, crash/reopen convergence, three-platform path safety, and a complete transitive-license audit.
4. Preserve the existing verified-runtime contract. runtimeIdentitySha256, owner binding, SQLite accepted truth, reservations, candidates, and successors remain valid. If feasible, the gitoxide backend will materialize ordinary Maka-owned projection directories and avoid Git linked-worktree registration, which should also simplify crash reconciliation.
5. Only reconnect managed workspace after the spike passes. If it does not pass, we will reassess a user-provided verified Git runtime or seek further ASF guidance. We will not ship an unverified PATH fallback.

For the first ASF release, we therefore propose treating managed workspace as a high-value optional capability rather than a prerequisite for the baseline Desktop artifact. This is an engineering/release plan, not a legal conclusion; mentor/IPMC/Legal guidance is still welcome, especially for any future download-based approach.

中文版本

感谢提出这个问题。近期我们准备按以下顺序处理：

1. 先从 ASF Desktop convenience artifact 中移除 bundled Git。 Git runtime 的交付方式属于实现细节，不作为首个版本的基础发布前提。在出现经过验证的替代实现之前，managed workspace 会在 admission/T1 之前明确报告不可用；一旦 durable mode 已经选定，T1 之后绝不静默 fallback。
2. 暂时不推进首次使用时自动下载 Git。 ASF 政策问题仍值得继续确认，但首发和下一阶段工程实现不依赖这个答案。
3. 进行有时间边界的 gitoxide 可行性验证。 gitoxide 使用 Apache-2.0/MIT 许可，很适合验证 Maka 当前只涉及本地 Git 的需求。我们会通过 Maka 自有的 Rust helper/library 边界接入，而不是依赖官方明确标为不稳定的 gix CLI。验证范围包括 object/tree/commit、ref CAS、确定性目录物化、崩溃重启收敛、三平台路径安全，以及完整的传递依赖许可证审计。
4. 保留已有 verified-runtime 合同。 runtimeIdentitySha256、owner binding、SQLite accepted truth、reservation、candidate 和 successor 均继续有效。如果验证可行，gitoxide backend 将直接物化普通的 Maka-owned projection 目录，尽量不再依赖 Git linked-worktree registration，从而简化崩溃恢复。
5. 验证通过后才重新接通 managed workspace。 如果验证失败，再评估用户显式提供并验证的 Git runtime，或继续请求 ASF 指导；不会引入未经验证的 PATH fallback。

因此，首个 ASF 版本暂时把 managed workspace 定位为高价值的可选能力，而不是 Desktop 基础发布物的硬前提。这是工程和发布计划，不是法律结论；对于未来可能的自动下载方案，我们仍欢迎 mentors/IPMC/Legal 的意见。

[zhiiw]

One implementation detail is worth making explicit: if we use gitoxide as an out-of-process broker, Maka will need a thin layer of Rust code.

The reason is practical rather than architectural preference:

• gitoxide is primarily a set of Rust libraries; its gix CLI is not the stable product boundary we want to depend on;
• Maka's Runtime Host is Node/TypeScript, so the library cannot be invoked directly without either an FFI boundary or a small native executable;
• an FFI binding would put Rust panics, native memory, ABI compatibility, and library lifecycle inside the Host process, while a broker gives us process-level crash isolation and a much narrower permission boundary;
• the broker must translate a very small, versioned protocol into exact repository operations, apply resource/path/hash-policy checks, and return stable error codes. This prevents the TypeScript side from depending on gitoxide's internal API shape;
• it also gives release engineering one explicit native artifact to build, audit, attest, and package.

The proposed Rust layer is therefore intentionally small. It is not a rewrite of Maka in Rust and it is not a general Git CLI. Its surface should remain limited to the managed-workspace primitives that we can prove, such as repository admission, exact object import/read/write, exact-base ref CAS, projection materialization, and bounded drift observation. SHA-256 repositories will initially fail closed behind an explicit capability seam rather than being partially supported.

Ordinary users will not need Rust installed. Rust is only a build/test dependency for producing the broker; release artifacts would contain the compiled executable. The Node/TypeScript application remains the control plane, SQLite remains the accepted-truth owner, and the Rust broker is only the local Git data-plane adapter.

This thin wrapper is the smallest credible way to obtain a stable protocol and fault boundary while using gitoxide. If we do not want to maintain any Rust code at all, then gitoxide is not a realistic broker choice and we would need to return to a separately supplied Git CLI or another executable implementation.

中文说明

这里需要明确一个实现事实：如果把 gitoxide 作为独立进程 broker 使用，Maka 就必须引入一层很薄的 Rust 代码。

原因不是我们偏好 Rust，而是实际边界决定的：

• gitoxide 主要是一组 Rust library；它的 gix CLI 不是我们希望长期依赖的稳定产品边界；
• Maka 的 Runtime Host 是 Node/TypeScript，无法直接调用 Rust library，必须在 FFI 和小型 native executable 之间选择；
• FFI 会把 Rust panic、native memory、ABI 兼容性和 library 生命周期带进 Host 进程；独立 broker 则能提供进程级崩溃隔离，以及更窄的权限边界；
• broker 只需把一个很小、带版本的协议翻译为精确 repository 操作，同时执行资源、路径和 hash policy 校验，并返回稳定错误码。这样 TypeScript 侧不需要依赖 gitoxide 内部 API 的变化；
• 发布流程也只需要构建、审计、证明并打包一个明确的 native artifact。

因此，这层 Rust wrapper 会被刻意保持得很薄。它不是把 Maka 重写成 Rust，也不是重新实现一个通用 Git CLI。它只暴露我们能证明的 managed-workspace 原语，例如 repository admission、精确 object 导入/读写、exact-base ref CAS、projection 物化，以及有资源上限的 drift observation。SHA-256 repository 初期会通过明确的 capability seam fail closed，而不是提供不完整支持。

普通用户不需要安装 Rust。Rust 只是在构建和测试 broker 时使用；发布包中只包含编译后的可执行文件。Node/TypeScript 应用仍是控制面，SQLite 仍是 accepted truth 的 owner，Rust broker 只承担本地 Git data plane adapter。

从 gitoxide 获得稳定协议和故障隔离时，这层薄 wrapper 是最小而可信的实现。如果完全不愿维护 Rust 代码，那么 gitoxide 就不适合作为 broker，只能重新考虑由用户提供并经过验证的 Git CLI，或其他已有的可执行实现。

[M4n5ter]

English

I agree with the core direction: Maka should own a thin Rust wrapper around the specific gix operations it needs instead of depending on the unstable gix CLI. Maintaining that wrapper should be quite manageable as long as its surface remains limited to the managed-workspace primitives listed above.

I do not think that wrapper necessarily needs to be an out-of-process broker, though. A stable product boundary and a process boundary are separate decisions.

Using N-API—practically, something such as napi-rs—we can expose a small set of coarse-grained asynchronous operations to the Runtime Host:

• repository admission and capability inspection;
• exact object import/read/write;
• exact-base ref CAS;
• deterministic projection materialization;
• bounded drift observation.

The Node side would only see Maka-owned DTOs and stable error codes; no gix types or APIs would cross the boundary. Blocking Git work can run outside the JavaScript event loop with bounded concurrency, while SQLite remains the accepted-truth authority and TypeScript remains the control plane.

This also preserves a verifiable runtime identity. Instead of hashing a Git executable, the backend manifest can identify a gitoxide_napi_v1 distribution and derive its identity from the packaged native-module bytes plus the declared wrapper/backend version and feature set. We still build, audit, attest, and package one native artifact per platform and architecture—the artifact is simply a .node module rather than a separately supervised executable.

An independent broker does provide stronger crash isolation, but it also introduces an IPC protocol, process startup and supervision, cancellation and shutdown semantics, diagnostic forwarding, executable discovery, and another lifecycle to reconcile. Merely moving code into another process also does not create a narrower permission boundary unless we actually run it under a different OS principal or sandbox.

My preference would therefore be:

1. Start with the smallest stable boundary: an in-process N-API wrapper exposing only Maka’s required primitives.
2. Make panic handling, input/resource limits, concurrency bounds, and stable error mapping explicit at that boundary.
3. Move the same API behind an out-of-process broker only if the feasibility work demonstrates a concrete need for abort/segfault containment, privilege separation, or independent lifecycle supervision.

That keeps the architecture small without closing the door on a broker later. The thin Maka-owned Rust wrapper is the important part; the extra process should have to justify itself separately.

简体中文

我赞同核心方向：Maka 应当围绕实际需要的 gix 操作维护一层很薄的 Rust wrapper，而不是依赖不稳定的 gix CLI。只要它的接口始终限定在上述 managed-workspace 原语内，这层 wrapper 的维护成本并不会很高。

不过，我不认为这层 wrapper 必须一开始就做成独立进程 broker。“稳定的产品边界”和“进程边界”是两个不同的设计决策。

通过 N-API——实际可以使用 napi-rs——我们可以向 Runtime Host 暴露少量粗粒度异步操作：

• repository admission 与 capability inspection；
• 精确的 object 导入、读取和写入；
• exact-base ref CAS；
• 确定性的 projection 物化；
• 有资源上限的 drift observation。

Node 侧只接触 Maka 自有的 DTO 和稳定错误码，不会直接依赖任何 gix 类型或 API。阻塞的 Git 操作可以在 JavaScript event loop 之外执行，并限制并发；SQLite 继续作为 accepted truth authority，TypeScript 继续承担控制面职责。

这也不会妨碍保留可验证的 runtime identity。backend manifest 可以定义 gitoxide_napi_v1 distribution，并基于打包后的 native module 字节、wrapper/backend 版本和 feature set 派生 identity，而不再依赖 Git executable hash。我们仍然需要为各平台和架构构建、审计、证明并打包一个 native artifact，只是该 artifact 是 .node module，而不是需要独立监督的 executable。

独立 broker 确实能够提供更强的崩溃隔离，但它同时会引入 IPC protocol、进程启动与监督、取消和 shutdown 语义、诊断转发、可执行文件定位，以及另一套需要收敛的生命周期。仅仅把代码移动到另一个进程，也不会自然形成更窄的权限边界；除非我们确实使用不同的 OS principal 或 sandbox 运行它。

因此，我更倾向于：

1. 从最小的稳定边界开始：使用进程内 N-API wrapper，只暴露 Maka 需要的原语。
2. 在该边界明确处理 panic、输入和资源限制、并发上限以及稳定错误映射。
3. 只有可行性验证证明我们确实需要 abort/segfault 隔离、权限分离或独立生命周期监督时，再把同一套 API 移到独立 broker 后面。

这样既能保持架构简单，也不会阻止以后升级为 broker。真正重要的是那层 Maka 自有的薄 Rust wrapper；额外的独立进程应当单独证明其必要性。

[zhiiw]

The N-API suggestion is useful because it separates two decisions that we had previously coupled too early:

1. Maka needs a thin, Maka-owned Rust API over the required gix primitives.
2. That API does not inherently have to live in a separate process.

I compared the three plausible topologies against Maka's current requirements:

Topology	Main advantage	Main shortcoming
In-process N-API (napi-rs)	Lowest call overhead and easy reuse of repository/object caches	Once native work has started it generally cannot be forcibly cancelled; a native abort/segfault affects the whole Runtime Host, and native task drain becomes part of the Host lifecycle
Short-lived Rust helper	Strong per-operation fault isolation, process-tree cancellation, and the simplest production-shaped kill/reopen testing	Process startup and request serialization overhead; repository caches are not reused between calls
Long-lived Rust broker	Retains process isolation while reusing caches and avoiding per-call startup	Adds persistent IPC, request multiplexing, cancellation, supervision, restart, drain, cache lifecycle, and in-flight reconciliation; killing the broker may affect several operations

A separate process is not automatically a stronger filesystem permission boundary. Unless it runs under a different OS principal or sandbox, it has essentially the same filesystem authority as the Host. Its immediate value is fault containment, hard termination, resource observation, and a clearer crash-test seam.

For Maka's current managed-workspace operations, the first integration should therefore be a short-lived helper executing one coarse-grained operation per invocation, not one process per object and not a resident daemon. Candidate capture, exact-base ref CAS, or projection materialization should each be internally complete helper operations. TypeScript writes the durable intent before spawning; SQLite remains the sole accepted-truth authority; abnormal exit is reconciled from Git artifacts rather than blindly retried.

This is the smallest topology that directly supports Maka's current cancellation and production-shaped crash requirements. It avoids committing to a resident broker lifecycle before measurements justify it. If profiling later shows that process startup and repeated repository opening are material bottlenecks, the same Maka-owned DTO/error contract can move behind a resident broker. N-API remains viable if we can prove that cooperative cancellation is sufficient and that Host-wide native failure is an acceptable blast radius.

The shared Rust core should remain transport-neutral so this topology decision does not leak into object/ref semantics. SHA-256 repositories should initially return an explicit unsupported capability, and all variants still require the same three-platform build matrix, runtime identity, resource bounds, path policy, and transitive-license audit.

中文说明

N-API 的建议很有价值，因为它把之前过早绑定的两个决策拆开了：

1. Maka 确实需要一层 Maka 自有、只封装必要 gix 原语的薄 Rust API；
2. 这层 API 并不天然必须运行在独立进程中。

结合 Maka 当前需求，三种形态的主要权衡如下：

形态	主要优势	主要不足
进程内 N-API（napi-rs）	调用开销最低，容易复用 repository/object cache	native 操作开始后通常无法强制取消；abort/segfault 会影响整个 Runtime Host；native task drain 会进入 Host 生命周期
短生命周期 Rust helper	单次操作故障隔离最强，可以终止进程树，也最容易做真实 kill/reopen 测试	存在进程启动与序列化成本，调用之间无法复用 repository cache
常驻 Rust broker	在保留进程隔离的同时复用 cache，避免每次启动	引入常驻 IPC、多路复用、取消、监督、重启、drain、cache 生命周期和 in-flight reconciliation；杀 broker 可能影响多个操作

独立进程不会自动获得更窄的文件权限。除非使用不同 OS 身份或 sandbox，否则它和 Host 基本拥有相同的文件系统权限。它当前真正提供的是故障隔离、硬终止、资源观测和更清晰的崩溃测试边界。

因此，Maka 首次接入更适合采用一次调用执行一个粗粒度操作的短生命周期 helper，而不是每个 object 启一个进程，也不是立刻建设常驻 daemon。candidate capture、exact-base ref CAS、projection materialization 应分别由一次 helper 调用内部完成。TypeScript 在 spawn 前写 durable intent；SQLite 继续是唯一 accepted-truth owner；异常退出后根据 Git artifact reconciliation，而不是盲目重跑。

这是当前最小且能直接满足取消与 production-shaped crash 要求的形态。它避免在性能数据出现以前建设常驻 broker 生命周期。如果以后 profiling 证明进程启动和重复打开 repository 是实际瓶颈，同一套 Maka-owned DTO/error contract 可以迁移到常驻 broker。只有在证明协作式取消足够、且能够接受 native 故障带走 Host 时，N-API 才更适合作为默认实现。

共享 Rust core 应保持 transport-neutral，避免进程形态渗入 object/ref 语义。SHA-256 repository 首版应明确返回 unsupported capability；三种方案都仍然需要三平台构建矩阵、runtime identity、资源限制、路径策略和完整的传递依赖许可证审计。

[M4n5ter]

English

I agree with this decision. A short-lived helper keeps the first integration small while providing the hard cancellation and fault-isolation boundary needed by the managed-workspace recovery tests. Keeping the Rust core transport-neutral also preserves a clean path to N-API or a resident broker later if measurements justify it.

简体中文

我赞同这个决定。短生命周期 helper 在保持首个实现足够小的同时，提供了 managed workspace 恢复测试所需的硬取消和故障隔离边界；共享 Rust core 保持 transport-neutral，也为后续基于实测数据迁移到 N-API 或常驻 broker 留出了清晰路径。