Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
4386631
docs: sync README, ARCHITECTURE and contributor docs with the impleme…
tonibergholm-codento Oct 20, 2026
f7a6c64
docs: describe the bucket CAS retry before NonFastForward
tonibergholm-codento Oct 20, 2026
5fcf39f
docs: fix stale read-only, pin-path and partial-clone walk statements
tonibergholm-codento Oct 20, 2026
8f5a64d
docs: separate opening gates from per-request read-only enforcement
tonibergholm-codento Oct 20, 2026
ec64546
docs: note bucket signature/transcript gap (#229), fix CLAUDE.md depe…
tonibergholm-codento Oct 20, 2026
50d53b5
Merge branch 'main' into docs/sync-2026-10-20
tonibergholm-codento Oct 20, 2026
7fcb8ed
docs: describe sc transcript drop and signed tombstones
tonibergholm-codento Oct 20, 2026
a1cf347
docs: give bucket remote syntax in README until the CLI skill covers it
tonibergholm-codento Oct 20, 2026
c2c1e30
Merge branch 'main' into docs/sync-2026-10-20
tonibergholm-codento Oct 20, 2026
03a7e1f
Merge branch 'main' into docs/sync-2026-10-20
tonibergholm-codento Oct 20, 2026
b2b32b9
docs: update object-size, by-id ceiling, bucket cap and tombstone wor…
tonibergholm-codento Oct 20, 2026
e6ead9d
docs: include a serving mode in the bucket serve example
tonibergholm-codento Oct 20, 2026
a89314f
Merge origin/main into docs/sync-2026-10-20; bucket remotes now serve…
tonibergholm-codento Oct 20, 2026
96810de
docs: distinguish receive-side from send-side --no-transcripts
tonibergholm-codento Oct 20, 2026
3e10098
docs: qualify --secrets-fd as unix-only and the identical-subtree mer…
tonibergholm-codento Oct 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
247 changes: 198 additions & 49 deletions ARCHITECTURE.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ recorded as an ADR in `docs/adr/`. Keep them in sync when the design changes.

Crate roles are what `ls crates/` + each `Cargo.toml` say; the rules are what
matters. Strict dependency direction: top-level adapters `{cli, desktop} → repo →
{vfs, gitio, crypto} → core`, with the separate leaf edges `repo → tlsio`
{vfs, crypto} → core` (`gitio → core` is linked by `cli`, never by `repo`), with the separate leaf edges `repo → tlsio`
**and `repo → objio`** (`tlsio` and `objio` are leaves — each depends on no
other workspace crate, not even `core`). **`core` must never depend on Git,
worktrees, or crypto.** **`gix` must stay quarantined in `gitio`** — if you
Expand Down
34 changes: 25 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,24 +25,40 @@ cargo fmt --all # format (CI enforces --check)
cargo clippy --workspace --all-targets -- -D warnings # lint (CI enforces this)
```

The workspace includes the Tauri desktop crate (`apps/desktop/src-tauri`), so on
Linux `cargo test --workspace` needs the Tauri v2 system packages (WebKitGTK
and friends; the exact list is in the `Install Tauri Linux prerequisites` step
of [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). If you touch the
desktop frontend, also run `npm ci`, `npm run typecheck` and `npm test` in
`apps/desktop` (see [`apps/desktop/README.md`](apps/desktop/README.md)).

The demos under `demo/` are independent end-to-end proofs and double as
integration tests — if you touch a subsystem, run the relevant `demo/run_*.sh`.

## The bar for a change

CI runs `fmt --check`, `clippy -D warnings`, `cargo test --workspace`, and
`cargo doc`. Your PR must be green on all of them. In addition:
CI (`ci.yml`) runs `fmt --check`, `clippy -D warnings`, `cargo test --workspace
--all-targets` (Linux and macOS) and `cargo doc` for the Rust workspace, plus a
`desktop` job (`npm ci`, `npm audit --audit-level=high`, typecheck, test).
Your PR must be green on all of them. Dependency changes also run the RustSec
`audit` workflow, and CodeQL, Scorecard, the SBOM generation, the
`vendor-provenance` check and a nightly `wire_decode` fuzz run live in their own
workflows. In addition:

1. **Every new behavior ships with a test.** Tests live in `#[cfg(test)] mod
tests` next to the code. A test that materializes to disk must clean up after
itself and assert the path is gone.
2. **Respect the dependency rule and quarantines** (enforced socially, not just by
the compiler): `cli → repo → {vfs, gitio, crypto, tlsio} → core` (`tlsio` is a
leaf with no workspace deps). `core` never depends on Git, worktrees, or
crypto. **`gix` stays in `gitio` only**; **RustCrypto stays in `crypto`
only**; **rustls/rcgen stay in `tlsio` only**. If you find yourself reaching
for `gix`, a RustCrypto type, or TLS elsewhere, add a function to
`gitio`/`crypto`/`tlsio` instead.
the compiler): the adapters `cli` and `desktop` sit on top of `repo`, and
`repo → {vfs, crypto} → core` plus the leaf edges `repo → tlsio` and
`repo → objio` (`tlsio` and `objio` have no workspace deps). `gitio` depends
only on `core`; `repo` never links it (`cli` links both and passes imported
snapshots down). `core` never depends on Git, worktrees, or crypto. **`gix`
stays in `gitio` only**; **RustCrypto stays in `crypto` only**;
**rustls/rcgen stay in `tlsio` only**; **the S3 SDK stays in `objio` only**.
If you find yourself reaching for `gix`, a RustCrypto type, TLS, or an
object-store SDK elsewhere, add a function to `gitio`/`crypto`/`tlsio`/`objio`
instead.
3. **Do not break the [core invariants in `CLAUDE.md`](CLAUDE.md#core-invariants-do-not-break)** —
content addressing (`BLAKE3(canonical_encoding)`), `Arc<[u8]>`-shared blobs, the
mode-scoped disk invariant (ephemeral = zero residue), and "never silently drop
Expand All @@ -57,7 +73,7 @@ Some changes get a security pass before merge as standing policy, not ad-hoc
judgment. If your PR does any of the following, say so in the PR description
and walk the checklist:

- **Touches `crates/crypto`, `crates/tlsio`, or any transport/wire code** →
- **Touches `crates/crypto`, `crates/tlsio`, `crates/objio`, or any transport/wire code** →
re-read the relevant [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md) section;
state in the PR whether any documented boundary moves. If one does, the PR
must also update `THREAT-MODEL.md` (and add an ADR if the decision changes).
Expand Down
80 changes: 51 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

A next-generation version control system built around a snapshot-and-tag model
(Jujutsu-inspired), with per-file permissions, native committed secrets, and
in-memory clones as the long-term thesis. Across 34 shipped phases, this
repository now proves that thesis end to end:
in-memory clones as the long-term thesis. Across 36 shipped phases plus the
P37 partial-clone series (37a-37d), this repository now proves that thesis end
to end:

1. **In-memory virtual worktrees** (the agent wedge) — fork N parallel worktrees
of a repo entirely in RAM, run and check out against each, and tear them down
Expand All @@ -22,28 +23,31 @@ repository now proves that thesis end to end:
durable `.sc/` repos, branches, three-way merge, history editing
(cherry-pick/rebase/amend/undo), durable multi-invocation agent sessions,
signed commits with session-transcript provenance, sparse and partial
checkouts, and local/ssh/HTTP+TLS/Git network transports. **Implemented
(Phases 3-34.)**
checkouts (including merge and agent sessions on a partial clone), local/
ssh/HTTP+TLS/bucket/Git network transports, and a read-only native desktop
browser. **Implemented (Phases 3-37.)**

The system builds on / interoperates with Git rather than replacing it: it
imports an existing Git repo's `HEAD` in-process (via `gix`), exports history
back to Git commits, and reaches hosted Git (e.g. GitHub) through a spawned
system-git mirror bridge.

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design,
[docs/adr/](docs/adr/) for the architecture decision records covering every
phase, and [CLAUDE.md](CLAUDE.md) for project conventions and the per-phase
capability map.
[docs/adr/](docs/adr/) for the architecture decision records (0001-0054) behind
every phase, and [CLAUDE.md](CLAUDE.md) for project conventions and the
per-phase capability map. [CONTRIBUTING.md](CONTRIBUTING.md) covers the
development workflow.

> ⚠️ **Pre-1.0, not independently audited — don't trust production secrets to it
> yet.** src-control implements real cryptography (committed-secret envelope
> encryption, encrypted protected paths, Ed25519 signed provenance, in-binary
> TLS), but these are MVP implementations that have **not had an independent
> security audit**. There are deliberate boundaries you should understand first —
> e.g. pre-Phase-33 convergent ciphertext in history stays equality-confirmable
> forever, `sc+https://` trust is TOFU pinning (the first connection to a host is
> unverified), and rotation cuts off future reads but cannot erase ciphertext
> already in history. They are consolidated in
> forever, `sc+https://` trust defaults to TOFU pinning (the first connection to
> a host is unverified unless you pre-pin it or opt into CA validation), and
> rotation cuts off future reads but cannot erase ciphertext already in
> history. They are consolidated in
> [docs/THREAT-MODEL.md](docs/THREAT-MODEL.md). Report vulnerabilities privately
> per [SECURITY.md](SECURITY.md).

Expand All @@ -60,23 +64,31 @@ crates/
Ed25519 signing (the ONLY crate that links RustCrypto)
tlsio/ TLS for the sc+https:// transport (the ONLY crate that links
rustls/rcgen; a leaf — no workspace deps)
objio/ object-store buckets for sc+wal:// and sc+s3:// remotes (the ONLY crate
that links the S3 SDK; a leaf — no workspace deps)
repo/ durable .sc repo — refs, branches, working tree, merge, history
editing, remotes, protection, GC, sparse/partial clone, transcripts,
transport
transport (ssh, sc+http(s), bucket WAL)
cli/ `sc` binary
apps/
desktop/ read-only Tauri v2 + React/TypeScript repository browser (see
apps/desktop/README.md); calls `repo` directly, never the `sc` binary
demo/
25 end-to-end proof scripts covering everything below, e.g.:
27 end-to-end proof scripts covering everything below, e.g.:
run_demo.sh independent before/after filesystem diff, zero residue
run_repo_demo.sh persistent repo end-to-end demo
run_ssh_remote_demo.sh ssh-native transport round trip
run_provenance_demo.sh signed history + rewrite-attack proof
run_transcript_demo.sh sealed agent-session transcript proof
```

Dependency direction is strict: `cli → repo → {vfs, gitio, crypto, tlsio} → core`
(`tlsio` is a leaf). Only `gitio` links `gix`, only `crypto` links RustCrypto,
and only `tlsio` links rustls, keeping the rest of the system Git-, crypto-,
and TLS-library-agnostic.
Dependency direction is strict: the adapters `cli` and `desktop` sit on top of
`repo`; `repo → {vfs, crypto} → core`, plus the leaf edges `repo → tlsio` and
`repo → objio` (`tlsio` and `objio` depend on no other workspace crate). `gitio`
depends only on `core`, and `repo` never links it: `cli` links both and passes
imported snapshots down. Only `gitio` links `gix`, only `crypto` links
RustCrypto, only `tlsio` links rustls, and only `objio` links the S3 SDK,
keeping the rest of the system Git-, crypto-, TLS- and object-store-agnostic.

## Quick start

Expand Down Expand Up @@ -113,9 +125,14 @@ cargo run --bin sc -- export --to /path/to/git/repo
bash demo/run_demo.sh
```

See `CLAUDE.md`'s Commands section for the full command surface (merge,
history editing, secrets lifecycle, sparse/partial clone, ssh/HTTP remotes,
session transcripts, and more).
Run `sc --help` (and `sc <command> --help`) for the full command surface:
merge, history editing, secrets lifecycle, sparse/partial clone, ssh/HTTP(S)/
bucket remotes, session transcripts, and more. The annotated reference lives in
the `sc-cli-reference` skill (`.claude/skills/sc-cli-reference/SKILL.md`), which
does not yet cover bucket remotes. Those take `sc remote add <name>
sc+wal://<dir>` or `sc+s3://<bucket>/<prefix>` (see ADR-0046), and `sc serve
--http 127.0.0.1:8730 --store <url> <serve-home>` serves a bucket from a
disposable instance (`--stdio` also works; `sc serve --help`).

## How Phase 1 works

Expand All @@ -142,13 +159,18 @@ permissions via encrypted paths (Phase 7, randomized sealing since Phase 33)
all ship alongside a full persistent, branchable, content-addressed VCS —
merge and history editing, durable multi-invocation agent sessions with
auto-merge, a commit-time secret scanner, secret/permission lifecycle
(rotation, escrow, revocation tombstones, bulk rewrap), signed commits with
sealed session-transcript provenance, sparse and partial checkouts, and local,
ssh-native, sc-native HTTP/TLS (with bearer-token auth and listener resource
limits), and Git (including hosted GitHub) network transports, plus private
branches sealed to a recipient set until publish. All 34 phases are
implemented and tested; `demo/` holds 26 independent end-to-end proofs, one
per major capability. Remaining follow-ons (transparent lazy-fetch,
per-case gap-tolerant merge on partial clones, CA-path validation alongside
TOFU pinning, rotate-for-paths, and similar hardening items) are tracked in
[ROADMAP.md](ROADMAP.md)'s Deferred section rather than being open MVP scope.
(rotation, escrow, revocation tombstones, bulk rewrap, `sc rewrap --rotate`
for protected paths), signed commits with sealed session-transcript
provenance (droppable through signed tombstones), sparse and partial checkouts (lazy want-by-id fetch, merge,
cherry-pick, rebase and agent sessions on a partial clone), and local,
ssh-native, sc-native HTTP/TLS (bearer tokens with expiry and rotation,
listener resource limits, TOFU pinning managed by `sc tls`, or CA validation
via `SC_HTTPS_CA_FILE`/`SC_HTTPS_CA=system`), bucket (`sc+wal://`, `sc+s3://`),
and Git (including hosted GitHub) network transports, plus private branches
sealed to a recipient set until publish and a read-only Tauri desktop
browser. All 36 phases and P37a-37d are implemented and tested; `demo/` holds
27 independent end-to-end proofs, one per major capability. Remaining
follow-ons (transcript drop delivery gaps, bucket compaction and gc, named
concurrent `sc ws` sessions, size/count clone filters, and similar hardening
items) are tracked in [ROADMAP.md](ROADMAP.md)'s Deferred section and as open
GitHub issues rather than being open MVP scope.
30 changes: 22 additions & 8 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,30 @@ it are consolidated in [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md). In brief:
nonce per seal). Content sealed *before* P33 used convergent encryption and
remains **equality-confirmable forever** — rotation cannot erase ciphertext
already in history.
- **Two confidential transports ship:** `sc+https://` (in-binary TLS with
accept-new TOFU pinning; the *first* connection to a host is unverified by
construction, and `SC_HTTPS_FINGERPRINT` / `SC_HTTPS_STRICT=1` close that
window) and `ssh://`. Plain `sc serve --http` remains **plaintext** and its
bearer tokens cross the wire in the clear — use it only on loopback or behind
the documented stream-mode proxy setup; prefer `sc+https://` for any public
bind.
- **Two confidential sc-native transports ship:** `sc+https://` (in-binary
TLS; by default accept-new TOFU pinning, so the *first* connection to a host
is unverified by construction, and `SC_HTTPS_FINGERPRINT`, `sc tls pin` or
`SC_HTTPS_STRICT=1` close that window; `SC_HTTPS_CA_FILE` / `SC_HTTPS_CA=system`
switch a client to CA validation instead, with no revocation checking) and
`ssh://`. Plain `sc serve --http` remains **plaintext** and its bearer
tokens (which can carry an expiry and be rotated) cross the wire in the
clear — use it only on loopback or behind the documented stream-mode proxy
setup; prefer `sc+https://` for any public bind.
- **Bucket remotes (`sc+wal://`, `sc+s3://`) put the bucket's ACL on the
perimeter.** Public content sits in the bucket as plaintext at rest and a
writer with raw bucket access can move refs outside the `sc` client; sealed
content stays ciphertext. A bucket cannot judge a transcript drop tombstone, so
it serves a dropped transcript's body next to the tombstone; the receiver
honors the drop only for a signer in its `[signers] trusted` list.
- Committed secrets injected by `sc run` live in an **authorized local process
context, not strong isolation** — same-user processes can observe the child
environment.
environment. `sc run --secrets-fd N` (unix only; other platforms refuse it) keeps them
out of the environment but is still not isolation.
- **`sc transcript drop` is not erasure either.** A drop travels as a signed
tombstone that a peer honors only when the signature comes from a key in its
`[signers] trusted` list; an unsigned drop is local-only, and any trusted
signer can hide transcripts on every peer that trusts them. Peers without
the tombstone keep the sealed body.
- **Rotation/revocation ≠ erasure.** They cut off *future* reads through the
current registry but cannot erase ciphertext already in history and copied to
other clones; real cutover of a leaked credential always means rotating the
Expand Down
1 change: 1 addition & 0 deletions docs/agents/ACCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ it as the revocation checklist. Written as OSTIF-audit follow-up T-14 (G-012).
| `GITHUB_TOKEN` — `ci.yml` | `contents: read` | Ephemeral per-run. |
| `GITHUB_TOKEN` — `codeql.yml` | `contents: read` top-level; analyze job adds `security-events: write`, `actions: read` | Ephemeral per-run. |
| `GITHUB_TOKEN` — `audit.yml` | `contents: read`, `checks: write`, `issues: write` (job-scoped as of audit T-20) | Files RustSec findings as public issues. |
| `GITHUB_TOKEN` — `fuzz.yml`, `sbom.yml`, `vendor-provenance.yml` | `contents: read` | Ephemeral per-run. Nightly `wire_decode` fuzz, weekly CycloneDX SBOMs, and the vendored-glib provenance check; none holds a write scope. |
| `GITHUB_TOKEN` — `scorecard_analysis.yml` | `read-all` top-level; job adds `security-events: write`, `id-token: write` | Publishes Scorecard results. |
| AI agents (Claude Code et al.) | `gh` CLI under the maintainer's auth: issue/PR create, comment, label, close; local commit + push | Operate the public triage pipeline (`issue-tracker.md`). **Excluded** from draft security advisories and private reports; security fixes need distinct human review (see vulnerability-response.md). Compromise playbook: incident-response class 2. |
| Dependabot | Version + security update PRs (cargo, npm, github-actions) | PRs merge only through the standing required checks. |
Expand Down
9 changes: 5 additions & 4 deletions docs/agents/domain.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ currently live in two root files — treat them as the glossary/context source:
pointer to it. The full per-phase narrative log is archived at
`docs/archive/claude-md-phase-log-2026-07.md`.
- **`ARCHITECTURE.md`** at the repo root — the full design and rationale.
- **`docs/adr/`** — 43+ ADRs (0001…) recording every significant decision;
- **`docs/adr/`** — 54 ADRs (0001…0054) recording every significant decision;
read the ADRs that touch the area you're about to work in. This is a
single-context repo, so there are no per-crate `crates/<name>/docs/adr/`
dirs — all decisions live in the one root `docs/adr/`.
Expand All @@ -33,11 +33,12 @@ Single-context repo:
/
├── CLAUDE.md ← working guide + capability map (AGENTS.md points here)
├── ARCHITECTURE.md ← full design + rationale
├── docs/adr/ ← 0001…0043+ architectural decisions (one root collection)
└── crates/ ← core, vfs, gitio, crypto, tlsio, repo, cli (one cohesive VCS domain)
├── docs/adr/ ← 0001…0054 architectural decisions (one root collection)
├── crates/ ← core, vfs, gitio, crypto, tlsio, objio, repo, cli (one cohesive VCS domain)
└── apps/desktop/ ← Tauri v2 read-only browser (a top-level adapter over repo)
```

(This is a seven-crate Rust workspace but **one** domain — a next-gen VCS — so a
(This is an eight-crate Rust workspace plus a desktop app but **one** domain — a next-gen VCS — so a
single context, not a multi-context `CONTEXT-MAP.md` layout.)

## Use the project's vocabulary
Expand Down
Loading