docs(saiph): design Saiph, a Scion-style VCS (RIG-5665) by rigel-mintaka · Pull Request #48 · RigelBuild/docs

rigel-mintaka · 2026-10-18T21:14:05Z

Summary

This is the design set for Saiph, Rigel's own version-control system. It follows Scion closely (Redesigning source control at Anthropic). Saiph is its own product and will live in its own repo, RigelBuild/saiph. Compass is its first client, and RIG-5558 continues unchanged as the git backend.

The set lives at docs/designs/saiph/:

Record	Covers
`README.md`	Overview, rulings, glossary, component map, work order, and an index of every open question
`store.md`	Changesets, blobs, refs, derived data, the `saiph.v1` API, the metadata database, tenancy, ACLs, and deviations from Scion
`client.md`	Our own `saiph` CLI, `saiphd` daemon and `saiph-cache`; want-only fetch; sparse and virtual checkouts; tokens; agent tools
`review.md`	Changes, versions, stack DAG, threads, approvals, the attention set, and readiness to land
`merge-queue.md`	Lanes without a global lock, speculative batches, bisection, auto-rebase, and the cheap-model fixer for trivial conflicts
`ci-cd.md`	`saiph-ci` on k8s Jobs, presubmit and postsubmit, TAP-style culprit finding, Rapid-style CD, and the REAPI cache
`git-bridge.md`	Trunk-only export to GitHub, history import, and per-repo cutover

Ledger

DL-578..DL-581 moved to the saiph surface and were rewritten.
New: DL-590..DL-626.
internal-vcs.md (the first draft) is deleted.

Rulings folded in

From Matt, recorded in RIG-5821:

Scope:
- Follow the full Scion design for server and client.
- Saiph is its own product and repo.
- Today's Saiph UI is renamed Sirius (RIG-5879).
- Two backends: the git backend stays.
- Agents on a native repo have no GitHub egress.
Client: our own, not jj.
Mirror: only trunk is mirrored to git.
Review: stacks form a DAG.
CI/CD: runs on k8s.
Merge queue: batching and bisection, plus a cheap-model fixer.

Status

Draft, not ready to merge. The open questions are indexed in README.md. The load-bearing ones must be answered before the record freezes.

Preview: https://compass-vcs-rig-5665-interna.docs-2ui.pages.dev/designs/saiph/readme/

Gates

rumdl is clean on 48 files.
design-ledger-gate is OK.
ref-gate is clean.

linear-code · 2026-10-18T21:14:11Z

RIG-5665

github-actions · 2026-10-18T21:15:50Z

Rigel public design docs preview: https://compass-vcs-rig-5665-interna.docs-2ui.pages.dev

Deployed from compass-vcs/rig-5665-internal-vcs-design at 184000c.

rigel-mintaka · 2026-10-18T22:16:30Z

Review note at head 286ad478:

Reviews run: a design-critic red-team, plus one full review (4 high, 6 medium, 1 low).
Findings: all 11 are folded in 286ad478. None are open.
Checks: check and deploy are green.
Waiting on: OQ-1 to OQ-6 need Matt's ruling (RIG-5821). The record freezes when it lands.

mattwilkinsonn · 2026-10-18T22:06:02Z

+The record is written against each recommendation. OQ-2 depends on OQ-1.
+OQ-3 depends on OQ-4.
+
+**OQ-1. What is the store?**


C, full Scion impl. Compass will be multi server and multi Runner in future. the one Server is just for dev dogfood.

Should we split the VCS out into it's own project though? or keep it within Compass? Not sure.

Leaning towards splitting it out and just making Compass natively use it. We need to make a product name for it.

We'll also need to design the CI/CD alongside it, can collect research on the best ways to do that thru the Scion post, how Twigg is doing CI, Google's CI/CD. We should put an emphasis on using k8s for this as well.

Noted: full Scion design, with many Servers and Runners. The split and the product name are now round-2 questions R2-1 and R2-2 in RIG-5821. I recommend a separate repo. CI/CD gets its own record in the set, with research on Scion, Twigg, Google TAP, and k8s engines underway.

mattwilkinsonn · 2026-10-18T22:06:36Z

+**Recommendation:** (a). Compass runs one Server. The Scion gains we want
+come from where checks and refs live, not from the object format.
+
+**OQ-2. What does an agent work in?** (depends on OQ-1)


What does Scion use? I want to mirror Scion as much as possible across the entire impl.

Scion's client keeps a bounded local object cache, plus sparse and virtual checkouts fed by a node daemon and a cache tier. Negotiation is want-only: trees are fetched recursively, then blobs. Changesets, commits, rebases, and merges all happen on the server. The rewrite mirrors this. Whether the agent client is jj with a custom backend (as Google does for Piper) or our own client is a round-3 question, after research.

mattwilkinsonn · 2026-10-18T22:08:44Z

+a shallow repo. jj does not support partial (blob-filtered) clones
+(jj-vcs/jj issue #8920), so a fill is shallow in history but full in files.
+
+**OQ-3. How does a PR branch follow a base move?** (depends on OQ-4)


I think we just make the git mirror the trunk branch, all PRs (if we even call them PRs) don't get mirrored.

We can rethink the entire VCS flow here we're not bound by git-isms. I want to use Scion as much as possible as the reference impl, with Twigg/Piper/Critique as the inspirations for some of the UIs and workflows.

Noted: trunk-only mirror, no git ideas, Scion as the reference implementation.

mattwilkinsonn · 2026-10-18T22:10:10Z

+the PR records the result. If GitHub refuses, use (a). A change's own
+workflow edits are refused in every option (D4).
+
+**OQ-4. What is the review unit?**


Same model as Critique/Twigg/jj. Easily able to stack changes ontop of each other, creating stack graphs. Not bound by linear stacks like GitHub.

The CI implementation ontop of the VCS can take advantage of all of this.

Noted: graph stacks (Critique/Twigg/jj), with CI built on them. The review record will define changes, versions, stack graphs, threads, and approvals.

mattwilkinsonn · 2026-10-18T22:13:42Z

+
+**Named decisions this record introduces:** D1–D4 in [Decisions](#decisions).
+
+Length: the record is about 3,100 prose words. The excess over the


This is a very large concept, the length bounds do not apply for this, and it can be split into multiple docs in a directory hierarchy as needed.

Noted: the length bound is dropped. The proposed layout is one directory with an overview and per-area records (R2-3 in RIG-5821).

mattwilkinsonn · 2026-10-18T22:15:29Z

+and it keeps red → green inside one PR. Twigg versions still exist in the
+store.
+
+**OQ-5. What GitHub egress does an agent keep?**


When fully implemented, and not needing Compass agents to work on any git repos, none. Compass agents will only use this VCS. the git/GitHub mirroring feature is only for people wanting to migrate existing repos, making a product or codebase more accessible to users (we'd keep Compass repo full mirrored for example).

Noted: a native repo has no GitHub egress. Mirroring is for migration and public visibility, and Compass stays fully mirrored.

mattwilkinsonn · 2026-10-18T22:20:04Z

+(RIG-5558 T9). Dropping `github.com` is defense in depth: it also stops
+reads that skip the Server.
+
+**OQ-6. How does this order against RIG-5558?**


We need to retain compatibility with git repos, for users who want to partially cutover to Compass, try it out, etc. We'll need to maintain two VCS backends basically, one for regular git users that uses the git mirrors approach, and one that connects to this new VCS. So 5558 proceeds, and becomes the backend of the VCS tools for any repo that remains on GitHub/git, this new VCS is the replacement that we'll cutover to when it's ready for our repos, and then offer to users as a feature.

Noted: OQ-6 → (a). RIG-5558 ships whole as the git backend, and the native VCS is a second backend. I've told compass-agent; nothing in its protocol, migrations, or decisions changes.

mattwilkinsonn · 2026-10-18T22:20:26Z

+  - a version moves by compare-and-swap on one Postgres row;
+  - the only advertised ref is trunk.
+
+  Not taken: Scion's Server-created commits (here the agent's jj creates


I think we should take all of it.

Noted: take all of it.

Server-held change store grown from the RIG-5558 T10 mirror; agents fill and sync jj only from the Server; GitHub stays the mirror and landing path. Files DL-578..DL-581. Six open questions for Matt. Refs RIG-5665 Co-authored-by: Matt Wilkinson <matt@rigel.build>

…RIG-5665) Per Matt's round-1 rulings on docs#48: a full Scion-style native VCS as a second backend beside RIG-5558. Replaces internal-vcs.md. Co-authored-by: Matt Wilkinson <matt@rigel.build>

…D, git bridge (RIG-5665) Moves the set to its own surface, docs/designs/saiph, per Matt (RIG-5821): Saiph is its own product and repo. Files DL-590..DL-626 and moves DL-578..DL-581. Co-authored-by: Matt Wilkinson <matt@rigel.build>

rigel-mintaka marked this pull request as ready for review October 18, 2026 22:16

rigel-mintaka requested a review from mattwilkinsonn as a code owner October 18, 2026 22:16

mattwilkinsonn reviewed Oct 18, 2026

View reviewed changes

rigel-mintaka marked this pull request as draft October 18, 2026 22:23

rigel-mintaka and others added 4 commits October 19, 2026 07:37

docs(compass): fold review findings into internal VCS record (RIG-5665)

8527237

docs(compass): rewrite as native VCS design set: overview and store (…

8560e83

…RIG-5665) Per Matt's round-1 rulings on docs#48: a full Scion-style native VCS as a second backend beside RIG-5558. Replaces internal-vcs.md. Co-authored-by: Matt Wilkinson <matt@rigel.build>

rigel-mintaka force-pushed the compass-vcs/rig-5665-internal-vcs-design branch from 11d6253 to 184000c Compare October 19, 2026 11:38

rigel-mintaka changed the title ~~docs(compass): design Compass-internal VCS (RIG-5665)~~ docs(saiph): design Saiph, a Scion-style VCS (RIG-5665) Oct 19, 2026


		Named decisions this record introduces: D1–D4 in [Decisions](#decisions).

		Length: the record is about 3,100 prose words. The excess over the

Conversation

rigel-mintaka commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Ledger

Rulings folded in

Status

Gates

Uh oh!

linear-code Bot commented Oct 18, 2026

Uh oh!

github-actions Bot commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rigel-mintaka commented Oct 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rigel-mintaka commented Oct 18, 2026 •

edited

Loading

github-actions Bot commented Oct 18, 2026 •

edited

Loading