From aca5ba5194990354ee2183d0f113e5e83b228e55 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 16:30:58 +0300 Subject: [PATCH 1/4] docs: sync CLAUDE.md, ROADMAP, THREAT-MODEL, skill reference and ADR status with the implementation Docs sync pass 2, re-verified against current main and sc --help. --- .claude/skills/sc-cli-reference/SKILL.md | 39 ++- ARCHITECTURE.md | 17 +- CLAUDE.md | 27 +- ROADMAP.md | 315 ++++++------------ crates/cli/src/main.rs | 14 +- crates/repo/src/protect_ops.rs | 2 +- crates/repo/src/repo.rs | 2 +- docs/THREAT-MODEL.md | 77 ++++- ...14-per-file-permissions-encrypted-paths.md | 2 +- docs/adr/0019-secret-lifecycle.md | 2 +- docs/adr/0020-six-crate-workspace.md | 2 +- docs/adr/0036-http-transport.md | 2 +- docs/adr/0037-partial-clone.md | 2 +- docs/adr/0040-sc-http-access-control.md | 2 +- docs/adr/0042-in-binary-tls-sc-https.md | 2 +- .../0043-randomized-protected-encryption.md | 2 +- .../adr/0047-want-by-id-fetch-and-gap-fill.md | 2 +- .../adr/0048-presence-based-partial-clones.md | 2 +- docs/adr/0049-merge-on-partial-clones.md | 2 +- docs/adr/README.md | 38 ++- docs/security/third-party-inventory.md | 3 +- 21 files changed, 290 insertions(+), 266 deletions(-) diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index c7183f53..58792988 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -15,9 +15,11 @@ cd apps/desktop && npm run tauri dev # native desktop development app cd apps/desktop && npm run tauri build -- --bundles app # validated macOS production bundle cargo run --bin sc -- demo --agents 4 # parallel-agent demo cargo run --bin sc -- demo --agents 6 --budget-mb 4 --spill # exercise eviction +cargo run --bin sc -- demo --agents 4 --checkout # also materialize each worktree to a session + # temp dir (the one disk-writing path), then clean up cargo run --bin sc -- import --repo # import a Git repo's HEAD bash demo/run_demo.sh # independent zero-residue proof -cargo run --bin sc -- keygen # v2 identity: one seed derives BOTH an X25519 +cargo run --bin sc -- keygen [--out ] # (default ~/.sc/identity, 0600) v2 identity: one seed derives BOTH an X25519 # encryption key and an Ed25519 signing key (P22); # a pre-P22 v1 (scl-sk-) identity still parses and # still encrypts, but cannot sign @@ -77,7 +79,9 @@ cargo run --bin sc -- resolve --ours|--theirs ... [--identity ] # merge/pick/rebase conflict record (P23) cargo run --bin sc -- scan # preview the commit-time secret scan cargo run --bin sc -- clone # copy a repo (objects + refs) -cargo run --bin sc -- protect --to # encrypt matching paths (P7) +cargo run --bin sc -- protect --to # encrypt matching paths (P7); sealing + # is randomized since P33 (ADR-0043) +cargo run --bin sc -- protect [--list] [--json] # list the protection rules (no prefix = list) cargo run --bin sc -- grant --to --identity # path-protection grant cargo run --bin sc -- revoke --recipient-id # path-protection revoke; # tombstone-durable across merges of pre-revoke @@ -102,8 +106,13 @@ cargo run --bin sc -- run [--secrets-fd N] -- [args…] # inject decrypt cargo run --bin sc -- gc # pack reachable objects + prune unreachable cargo run --bin sc -- gc --prune-expire 7d # custom grace window cargo run --bin sc -- export --to # write current branch history to Git +cargo run --bin sc -- export --to --ref # update this Git ref instead of + # refs/heads/ cargo run --bin sc -- export --to --include-encrypted # allow protected ciphertext bash demo/run_repo_demo.sh # end-to-end persistent repo proof +bash demo/run_remote_demo.sh # local-path remote round trip (P6): clone, then + # fetch+merge and push between two local repos +cargo run --bin sc -- remote list # name, URL and kind ([sc] / [git]) of each remote cargo run --bin sc -- remote add --git # register a git-backed remote cargo run --bin sc -- fetch # import git history -> remote-tracking ref cargo run --bin sc -- push [--include-encrypted] # export sc history -> git ref (ff-only) @@ -141,8 +150,9 @@ bash demo/run_randomized_demo.sh # randomized protected-enc # rewrap UPGRADE and pre-P33 dual-read are unit- # test-pinned, since the current binary can no # longer write a convergent blob) -cargo run --bin sc -- work --agents 3 -- # fork agent workspaces, run in each, - # harvest changed ones to work- branches +cargo run --bin sc -- work --agents 3 [--name ] -- # fork agent workspaces, run + # in each, harvest changed ones to + # - branches (default base `work`) # (--with-secrets --identity injects # decrypted secrets into each agent env) bash demo/run_work_demo.sh # parallel-agents round-trip proof @@ -156,7 +166,8 @@ cargo run --bin sc -- ws harvest [--into ] [--identity ] # probe # every live workspace onto the landing branch # (default the session's base branch, which must # be checked out); clean lands cumulatively, - # conflicts fall back to work- + # conflicts fall back to work- (always `work`; + # `--name` is `sc work` only) cargo run --bin sc -- ws abandon [] # drop one workspace or the whole session bash demo/run_ws_demo.sh # multi-invocation session + auto-merge proof (P20) cargo run --bin sc -- cherry-pick [--identity ] # replay one commit onto the @@ -333,6 +344,21 @@ cargo run --bin sc -- serve token list [--json] # list labels, scopes, expiry cargo run --bin sc -- clone sc+http://host[:port]/repo # clone over sc+http:// (P26; # port defaults to 8730); sc remote add/fetch/push # accept the same sc+http:// URL form +cargo run --bin sc -- remote add sc+wal:// # bucket WAL remote on a local + # directory (P36, ADR-0046); `clone`/`fetch`/`push` + # take the same URL form +cargo run --bin sc -- remote add sc+s3:/// # same, on an S3-compatible + # store; a malformed URL (e.g. no bucket) is rejected + # at `remote add` time. Public content is plaintext at + # rest (the bucket ACL is the perimeter; sealed + # content stays ciphertext); `clone --filter` is + # refused; signatures, transcripts and drop + # tombstones travel like on any native remote (#229) +cargo run --bin sc -- serve --http --store sc+wal://|sc+s3:/// + # serve a bucket remote over sc+http(s):// (P36c): + # all content lives in the bucket (instance is + # disposable); still needs `.sc/` for tokens, + # the TLS identity and scratch space bash demo/run_http_remote_demo.sh # sc-native HTTP transport proof (P26): real # loopback TCP (no shim, unlike ssh://), clone + # push + fetch over sc+http://, a signed ~1 MiB @@ -378,6 +404,9 @@ bash demo/run_partial_clone_demo.sh # partial clone proof (P27): sc cl # edit AND byte-identical docs/lib); sc backfill # docs/ shrinks the gap count; sc gc succeeds and # preserves everything; run twice +bash demo/run_limits_demo.sh # listener-limits proof (P31): --max-connections + # busy shed and slot reuse, --timeout and + # --max-pack-size parse and take effect bash demo/run_http_auth_demo.sh # sc+http access-control proof (P29): a no-token # clone is rejected with an authentication error, # an ro-token clone reads but its push is rejected diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7d1cd135..f5617097 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -356,7 +356,8 @@ phases but the shape is stable: `PICK_HEAD`, `REBASE_STATE`, and their `*_DECIDED_ROOT` records, plus `CONFLICT_PLAINTEXT` / `CONFLICT_SIDECARS` listing what a stopped operation wrote into the working tree — an interrupted merge/pick/rebase resumes or - aborts cleanly from these. + aborts cleanly from these. `sparse-widen` records the files a widening + `sparse set` is laying out while an operation is stopped (P24, #224). - The `sc+https://` client's pin file is user-level, not part of `.sc/` (`$SC_HTTPS_KNOWN_HOSTS`, else `$XDG_CONFIG_HOME/sc/known_hosts`, else `~/.config/sc/known_hosts`; managed with `sc tls`). @@ -369,6 +370,10 @@ branch ref. `switch` materializes the target branch tip into the working tree, removing tracked files that are absent from the target, and refuses the operation if tracked files are modified or deleted (to prevent data loss). New, untracked files are left in place. `status` diffs the working tree against HEAD. +Every write-out path (switch, merge, rebase, `sparse set`, clone, `ws fork`, +private and conflict write-outs) applies the recorded file mode through one +helper, so an executable file stays executable on unix and a stale execute bit +is cleared on a plain file (#242). ### Mode-scoped disk invariant @@ -845,7 +850,10 @@ workspace's never-materialized paths as deletions. A clean merge/pick/rebase change to an out-of-sparse path lands in the CAS without materializing; a CONFLICT there refuses up front with a "run `sc -sparse set` to include it" hint. Sparse is CHECKOUT-only — every object +sparse set` to include it" hint. While the operation is stopped, `sparse set` +accepts only a strict widen (the new spec covers the old one): it lays out the +newly in-view files from the stop's decided root, leaves protected ones absent, +and the interrupted write is journaled in `.sc/sparse-widen` (#224). Sparse is CHECKOUT-only — every object stays in the CAS regardless of the spec, so `sc gc`'s reachability walk is unaffected; not fetching out-of-prefix objects at all is deferred to P27. See ADR-0034. @@ -1004,6 +1012,11 @@ opening, connection-fatal on trip since a mid-stream abort desyncs the frame stream), and `--max-pack-size` (default 16 GiB, floor = the max object size, 256 MiB by default; lives in the shared `WirePolicy`, so it applies to both `--http` and `--stdio`; a counted mid-stream abort replies `EC_TOO_LARGE`). +Later additions to the same policy: `--max-object-size` (operator-configurable +per-object cap, #213) and `--max-conn-bytes`, a per-connection write budget on +both transports that counts every `PutObject` and each `PutPack`'s larger of +spool and decoded bytes, replies `ConnectionBudgetExceeded` and closes (#233, +no `PROTOCOL_VERSION` change; see the ADR-0039 addenda). The read-only pre-drain is capped at 8 MiB (`RO_DRAIN_CAP`), and the accept loop gained a hardcoded Go-`net/http`-shaped exponential backoff around fd diff --git a/CLAUDE.md b/CLAUDE.md index 3673405d..c813b57d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,8 @@ recorded as an ADR in `docs/adr/`. Keep them in sync when the design changes. ## Stack & tooling -- **Language:** Rust (stable). Rationale in ARCHITECTURE.md ("Why Rust"). +- **Language:** Rust, toolchain pinned to 1.96.1 (`rust-toolchain.toml`, `rust-version`, + and CI use the same tag; bump all three together). Rationale in ARCHITECTURE.md ("Why Rust"). - **Desktop:** Tauri v2 + React/TypeScript under `apps/desktop/`; frontend dependencies are bundled and remain presentation-only. - **Edition:** 2021, inherited via `[workspace.package]`. @@ -116,8 +117,8 @@ the code, those win. | Phase | Current state | ADR | |---|---|---| | P1 | In-RAM copy-on-write virtual worktrees; bounded blob budget + LRU eviction, optional spill; zero disk residue | [0005](docs/adr/0005-in-ram-vfs-over-fuse.md), [0006](docs/adr/0006-memory-budget-and-eviction.md) | -| P2 | Committed secrets: per-secret DEK (XChaCha20-Poly1305) wrapped per X25519 recipient; secrets are env vars, never files — `checkout` never materializes them; `sc run` injects into a child env | [0008](docs/adr/0008-committed-secrets-envelope-encryption.md), [0009](docs/adr/0009-key-management-and-authorization.md), [0010](docs/adr/0010-secret-registry-and-opaque-wrapped-dek.md) | -| P3 | Persistent `.sc/` repo: loose objects, branches, symbolic HEAD, single-writer lock, working tree | [0011](docs/adr/0011-persistent-store-and-working-tree.md) | +| P2 | Committed secrets: per-secret DEK (XChaCha20-Poly1305) wrapped per X25519 recipient; secrets are env vars, never files — `checkout` never materializes them; `sc run` injects into a child env, or onto a descriptor with `--secrets-fd N` (unix) | [0008](docs/adr/0008-committed-secrets-envelope-encryption.md), [0009](docs/adr/0009-key-management-and-authorization.md), [0010](docs/adr/0010-secret-registry-and-opaque-wrapped-dek.md), [0052](docs/adr/0052-secret-injection-by-fd.md) | +| P3 | Persistent `.sc/` repo: loose objects, branches, symbolic HEAD, single-writer lock, working tree; every write-out path restores the recorded executable bit (unix; #242) | [0011](docs/adr/0011-persistent-store-and-working-tree.md) | | P4 | Snapshot-DAG three-way merge; ff when possible; conflict markers + `.theirs` sidecars | [0012](docs/adr/0012-three-way-merge.md) | | P5 | Commit-time secret scanner (pattern + entropy) hard-rejects plaintext secrets; `sc scan` preview; hash-scoped allowlist | [0017](docs/adr/0017-secret-scanner.md) | | P6 | Local-path remotes: `clone`/`fetch`/`push`, remote-tracking refs, `Transport` trait | [0013](docs/adr/0013-remote-sync-model.md) | @@ -127,11 +128,11 @@ the code, those win. | P10 | Local Git repo as a first-class remote via a persisted `git_oid ↔ sc_id` marks map | [0018](docs/adr/0018-git-as-a-remote.md) | | P11 | `sc secret rotate` (fresh DEK) + escrow keys; rotation ≠ erasure (old ciphertext stays in history) | [0019](docs/adr/0019-secret-lifecycle.md) | | P12 | ssh:// transport: framed stdio wire protocol, `sc serve --stdio`, client spawns `ssh` (`SC_SSH` overrides) | [0022](docs/adr/0022-ssh-native-transport.md) | -| P13 | `sc work --agents N`: one-shot in-RAM agent workspaces, harvested to flat `work-` branches | [0023](docs/adr/0023-agent-workspaces.md) | +| P13 | `sc work --agents N [--name ]`: one-shot in-RAM agent workspaces, harvested to flat `-` branches (default `work`) | [0023](docs/adr/0023-agent-workspaces.md) | | P14 | History editing: `cherry-pick`/`rebase` as replay; append-only `.sc/oplog`; `sc undo` (twice = redo) | [0024](docs/adr/0024-history-editing.md) | | P15 | Protected merge/replay: ciphertext-id fast paths; `--identity` only for content-divergent protected paths; rules merge by union; secret registry replays | [0025](docs/adr/0025-protected-merge-and-replay.md) | | P16 | Durable revocation: per-recipient epoch LWW tombstones; epoch tie resolves Revoked (fail-closed); snapshot tag 4 | [0026](docs/adr/0026-revocation-tombstones.md) | -| P17 | `sc rewrap`: one-commit bulk cutover of secrets + protected wrap lists to current recipients/escrow; escrow is a managed list | [0027](docs/adr/0027-bulk-rewrap-and-multi-escrow.md) | +| P17 | `sc rewrap`: one-commit bulk cutover of secrets + protected wrap lists to current recipients/escrow; escrow is a managed list; `--rotate` also re-seals every protected blob under a fresh key | [0027](docs/adr/0027-bulk-rewrap-and-multi-escrow.md), [0051](docs/adr/0051-rotate-protected-paths.md) | | P18 | Hosted Git (GitHub https/ssh) via system-git mirror bridge (`SC_GIT` overrides); auth delegated to git | [0028](docs/adr/0028-network-git-remotes.md) | | P19 | Resumable rebase (stop → resolve → `--continue`; one oplog record total), `cherry-pick --abort`/`--mainline `, `sc amend` | [0029](docs/adr/0029-history-editing-polish.md) | | P20 | Durable multi-invocation agent sessions: `sc ws fork/list/run/harvest/abandon` under `.sc/ws/`; harvest auto-merges, conflicts fall back to `work-` | [0030](docs/adr/0030-agent-sessions-and-automerge.md) | @@ -143,10 +144,10 @@ the code, those win. | P26 | `sc+http://` transport: `sc serve --http`, thread-per-connection, status-line-before-handshake opening | [0036](docs/adr/0036-http-transport.md) | | P27 | Partial clone: `sc clone --filter `, `.sc/promisor`, `sc backfill [--all]`; wire `PROTOCOL_VERSION` 3 | [0037](docs/adr/0037-partial-clone.md) | | P28 | Security hardening: a max object size (default 256 MiB; `--max-object-size` / `SC_MAX_OBJECT_SIZE`, 2 MiB to 1 GiB) caps every untrusted transfer length; strict ref-name validation | [0039](docs/adr/0039-security-hardening-sweep.md) | -| P29 | `sc serve --http` access control: bearer tokens (`sc serve token`), `--read-only`, fail-closed non-loopback bind gate | [0040](docs/adr/0040-sc-http-access-control.md) | +| P29 | `sc serve --http` access control: bearer tokens (`sc serve token add [--expires]`/`rotate`/`remove`/`list`; an expired token gets the same 401 as an unknown one), `--read-only`, fail-closed non-loopback bind gate | [0040](docs/adr/0040-sc-http-access-control.md) | | P30 | Sealed agent-session transcripts: `sc transcript attach/show/list/sign/drop`, always-encrypted body, gc-coupled index; `--no-transcripts` on fetch/clone/push (client-side, per command); drop = grow-only tombstone (a bare `Transcript` object, no wire change), kept by gc, hides the body from fetch/reindex | [0038](docs/adr/0038-agent-session-transcripts.md) | -| P31 | Listener resource limits: `--max-connections`, `--timeout`, `--max-pack-size` (both transports), capped read-only drain, accept backoff | [0041](docs/adr/0041-listener-resource-limits.md) | -| P32 | In-binary TLS: `sc+https://` via leaf crate `tlsio`; accept-new TOFU pinning; public plaintext bind no longer justified by tokens alone | [0042](docs/adr/0042-in-binary-tls-sc-https.md) | +| P31 | Listener resource limits: `--max-connections`, `--timeout`, `--max-pack-size` (both transports), capped read-only drain, accept backoff; later `--max-conn-bytes` per-connection write budget (#233) | [0041](docs/adr/0041-listener-resource-limits.md) | +| P32 | In-binary TLS: `sc+https://` via leaf crate `tlsio`; accept-new TOFU pinning (`sc tls list/forget/pin/path` manages the pin file); `SC_HTTPS_CA_FILE`/`SC_HTTPS_CA=system` validate against a CA instead; client connect/handshake bounded; public plaintext bind no longer justified by tokens alone | [0042](docs/adr/0042-in-binary-tls-sc-https.md), [0053](docs/adr/0053-tls-pin-management.md), [0054](docs/adr/0054-tls-ca-validation.md) | | P33 | Randomized protected sealing (fresh DEK + nonce; `RANDOMIZED` perms bit); dual-read of pre-P33 convergent ciphertext; per-checkout keyed stat cache; `sc rewrap` upgrades convergent blobs at the tip | [0043](docs/adr/0043-randomized-protected-encryption.md) | | P34 | Private branches: ref points at a sealed-branch manifest; every commit/tree/blob individually sealed (copy-on-write) under a per-branch KEK wrapped per recipient + escrow; `sc branch --private/grant/revoke/publish`; opaque to non-recipients (content, paths, messages); grant O(1), revoke rotates the KEK; publish replays to public with a scanner gate; git bridge + private→public integration refused; `PROTOCOL_VERSION` 4 | [0044](docs/adr/0044-per-branch-access-control.md) | | P35 | Native Tauri desktop browser: opens `.sc` repositories through `scl-repo`, shows local/remote refs, all-parent snapshot DAG + provenance, public trees and first-parent diffs; protected content is locked and private branches remain opaque; no mutation or identity surface | [0045](docs/adr/0045-native-desktop-read-model.md) | @@ -290,11 +291,11 @@ transport-adjacent. The rest, imperatively: ## Follow-ons Deferred work is tracked in **`ROADMAP.md` → Deferred** (single source of -truth — do not re-list items here). Notable standing entries: transparent -lazy-fetch for partial clones, per-case gap-tolerant merge/replay on partial -clones. `sc tls list/forget/pin/path` manages the `sc+https://` pin file -(ADR-0053); `SC_HTTPS_CA_FILE=` / `SC_HTTPS_CA=system` switch a client to CA -validation instead of pinning (ADR-0054). +truth — do not re-list items here); entries that name an issue mirror the open +GitHub issues. Standing entries: named/concurrent `sc ws` sessions (#215), +blob-size clone filters (#217), bucket compaction and gc (#216), the non-unix +`.sc/local-key` ACL (#214), transcript-drop delivery gaps (#230), and the open +sparse, private-branch and abort edge cases (#240, #241, #246, #247, #248, #243). ## Agent skills diff --git a/ROADMAP.md b/ROADMAP.md index b3739943..7eab7ffe 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -550,26 +550,63 @@ across every phase. remain opaque; the slice has no mutation, decryption, or general filesystem IPC. `@pierre/trees` remains exact-pinned to its current beta and should be reconsidered when its stable release is published. (ADR-0045.) +- **Phase 36 — Bucket WAL remotes (`sc+wal://`, `sc+s3://`).** A remote that + is only a bucket: immutable packs, a log of versioned entries and one + compare-and-swap manifest, so no long-lived server is needed to push or + fetch. P36a added the `objio` leaf crate (`Bucket` trait, directory and S3 + backends, the S3 SDK quarantined there) and `BucketTransport`; P36b added + checkpoints so a cold start reads the tail of the log, not all of it; P36c + added `sc serve --store `, a bucket-backed serve whose instances are + disposable (tokens, TLS identity and scratch stay in a local serve home). + Public content is plaintext at rest (the bucket ACL is the perimeter); + `clone --filter` is refused. `get_pack` serves signatures, transcripts and + signed drop tombstones by decoding the on-chain packs (#229, no format + change). (ADR-0046.) +- **Phase 37a — Want-by-id fetch.** A batched `GetObjects` verb (wire v5), an + opt-in `.sc/promisor-lazy` marker, and `sc cat :`, which fills only + the absent trees and the blob on its path. `Store::get` stays network-free. + Proven by `demo/run_lazy_fetch_demo.sh`. (ADR-0047.) +- **Phase 37b — Presence-based partial clones.** 37b-i: push, verify and gc walk + what the store holds, not the fetch filter; a view gap fails with `GapInView` + before any write. 37b-ii: on a lazy, online clone the view closure is filled + by id before switch, fast-forward, undo and `sparse set`, and `sparse set` may + widen past the filter. (ADR-0048.) +- **Phase 37c — Merge, cherry-pick and rebase on a partial clone.** A + tree-recursive three-way engine carries a subtree by id where the sides agree + and no protection rule applies; conflicts inside the view are marked and + resolved as on a full clone, conflicts outside it are refused before any + write. (ADR-0049.) +- **Phase 37d — Agent sessions on a partial clone.** `sc ws` and `sc work` work + on a partial clone: a workspace sees the host's sparse view, and harvest lands + through the ADR-0049 merge. (ADR-0050.) +- **Post-P37 additions (phase-less).** + - `sc rewrap --rotate` re-seals every protected blob at the tip under a fresh + DEK (ADR-0051). + - `sc run --secrets-fd N` hands secrets to the command on a descriptor instead + of its environment (ADR-0052). + - `sc tls list/forget/pin/path` manages the `sc+https://` pin file (ADR-0053); + `SC_HTTPS_CA_FILE` / `SC_HTTPS_CA=system` validate against a CA instead of + pinning (ADR-0054). + - `sc serve token add --expires` and `token rotate` (#209, ADR-0040). + - The four P32 TLS follow-ons: no minting outside a repo, a warning for + `SC_HTTPS_*` on a plaintext URL, bounded client connect/handshake, and + `remote add` validation of `sc+http(s)://` URLs (#208). + - `--max-object-size` / `SC_MAX_OBJECT_SIZE` (#213) and the per-connection + write budget `sc serve --max-conn-bytes` (#233); ADR-0039 addenda. + - `--no-transcripts` on clone, fetch and push (#211) and + `sc transcript drop` with signed tombstones (#212); ADR-0038 addendum. + - Sparse follow-ups: a partial clone checks a `.theirs` sidecar by its base + path, and `sc sparse set` may widen while a merge, pick or rebase is stopped + (#224, #236); a stopped completion no longer resurrects out-of-view + deletions (#239). + - Checkout restores the executable bit on every write-out path (#242). + - A warning when the protected-cache key cannot be permission-restricted on a + non-unix target (#225; the owner-only ACL is #214). ## Active -**P37b — presence-based walks and the lifted P27 refusals (37b-i, 37b-ii built).** -P37a (built) added the batched `GetObjects` verb and `sc cat`. 37b-i (built) -made push, verify and gc ask "is this object present?" instead of "is this -path in the filter?", which also fixed gc and fast-forward failing after an -ordinary fetch on a partial clone. 37b-ii (built) added sparse widen on a lazy -clone: the view closure is filled by id before switch, fast-forward, undo and -`sparse set`, and a by-id reply is capped and split on refusal. `export` and -`sparse disable` stay refused. Design and open questions in -[ADR-0048](docs/adr/0048-presence-based-partial-clones.md). - -**P37c — merge on partial clones (built; 37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay).** A tree-recursive three-way merge -that carries a subtree by id where the three sides agree, checks protection -rules before carrying, never drops wraps for subtrees it does not enumerate, -and fills (lazy) or refuses (otherwise) the region where the sides differ, -the region that intersects a protection rule, and the sparse view's closure. Merges are built (`sc merge` on a partial clone): a conflict inside the view is marked, resolved with `sc conflicts`/`sc resolve`, aborted or committed like on a full clone; a conflict outside the view, or one that needs sealing outside it, is refused before any write. Cherry-pick and rebase use the same engine and conflict contract (`sc cherry-pick`, `sc rebase` and their `--continue`/`--abort` work on a partial clone); sessions are built (P37d, [ADR-0050](docs/adr/0050-sessions-on-partial-clones.md)): workspaces and -agents see the clone's view, and harvest lands through this merge. Design in -[ADR-0049](docs/adr/0049-merge-on-partial-clones.md). +No phase is in flight. Follow-up work is tracked as GitHub issues and listed +under Deferred below. ## Completed phases (usability-first ordering) @@ -598,7 +635,7 @@ agents see the clone's view, and harvest lands through this merge. Design in | **P24 — Sparse checkouts / sub-tree sharing** | Materialize one subtree of a large repo, leave the rest on the CAS | `sc sparse set `/`show`/`disable`; `commit`'s absent-path carry widens to out-of-sparse paths (byte-identical carried subtrees); `materialize` filters both its write and removal loops; proven by `demo/run_sparse_demo.sh` (narrow, edit, commit, then disable/clone restore byte-identical) | [0034](docs/adr/0034-sparse-checkouts.md) | | **P25 — Streaming pack transfer (bounded-RAM, >4 GiB)** | `push`/`fetch`/`clone` over ssh:// don't hold a whole pack in RAM anywhere — server, wire, or client | `PackWriter`/`parse_pack_reader` (bounded-RAM pack build/parse); `ST_PACK_CHUNK`/`ST_PACK_END` chunk framing (`SC_PACK_CHUNK`-tunable); `PROTOCOL_VERSION` 2, v1 dropped; two-pass atomic-after-verify ingest + `TempPackGuard`; the ssh client's own `sync.rs` fetch/push call sites route through the same `ingest_pack_file`/`write_ids_to_temp_pack` machinery (final-review fix); proven by `demo/run_streaming_demo.sh` (forced 4 KiB chunks, byte-for-byte clone, signature rides the stream, zero temp residue) | [0035](docs/adr/0035-streaming-transfer.md) | | **P26 — sc-native HTTP transport** | Reach a repo over plain TCP with no ssh account | `sc serve --http `; `sc clone sc+http://host[:port]/repo`; thread-per-connection server, opening-status mapped before the wire handshake, P25 chunk stream + P22 signatures ride the raw socket with no HTTP framing; proven by `demo/run_http_remote_demo.sh` (real loopback TCP, no shim; clone/push/fetch byte-for-byte, signed commit verifies clean, zero `.sc/tmp` residue) | [0036](docs/adr/0036-http-transport.md) | -| **P27 — Partial clone** | Bound network transfer to a subset of paths, not the whole repo | `sc clone --filter ` fetches only in-filter objects (`.sc/promisor` + filtered reachability walk); `sc backfill ` widens on demand; `sc gc`/`sc verify` are gap-tolerant; merge/rebase/`ws harvest`/`sc work`/`sc export` refuse on a partial clone; proven by `demo/run_partial_clone_demo.sh` (fewer objects fetched, push composes after a partial-clone commit, backfill shrinks the gap count, gc preserves everything, run twice) | [0037](docs/adr/0037-partial-clone.md) | +| **P27 — Partial clone** | Bound network transfer to a subset of paths, not the whole repo | `sc clone --filter ` fetches only in-filter objects (`.sc/promisor` + filtered reachability walk); `sc backfill ` widens on demand; `sc gc`/`sc verify` are gap-tolerant; merge/rebase/`ws harvest`/`sc work`/`sc export` refused on a partial clone (the merge, replay and session refusals were lifted by P37c/P37d; `export` still refuses); proven by `demo/run_partial_clone_demo.sh` (fewer objects fetched, push composes after a partial-clone commit, backfill shrinks the gap count, gc preserves everything, run twice) | [0037](docs/adr/0037-partial-clone.md) | | **P28 — Security hardening sweep** | Close the audit's concrete-bug Highs + surface the accepted Mediums | strict ref-name validation at the write/read boundary (hostile wire `UpdateRef` + git-remote branch names rejected); `MAX_OBJECT_SIZE` caps every untrusted frame/pack-record/zstd-output length; `sc protect` nudges low-entropy secret filenames toward `sc secret`; secret env-var boundary documented as authorized-local-process-context + plaintext stays `Zeroizing`; every prior demo green + new pinned regression tests, no new dependency | [0039](docs/adr/0039-security-hardening-sweep.md) | | **P29 — sc+http access control** | Close the audit's remaining unauthenticated-server High | fail-closed non-loopback bind; `sc serve token add/remove/list` + `SC_HTTP_TOKEN` bearer auth at the HTTP opening (constant-time `BLAKE3` compare, `401` before the wire handoff); `--read-only`/`ro`-scope tokens reject mutating verbs before any store write via `EC_READONLY`; proven by `demo/run_http_auth_demo.sh` | [0040](docs/adr/0040-sc-http-access-control.md) | | **P30 — Agent session transcripts** | Attach a sealed, provenance-checked agent-session record to a commit | `sc transcript attach --agent claude --sign`; a keyless clone gets ciphertext only, the recipient's identity decrypts byte-exact; `sc log` shows a non-decrypting presence marker; `sc gc` prunes a transcript once its only snapshot is unreachable; proven by `demo/run_transcript_demo.sh` | [0038](docs/adr/0038-agent-session-transcripts.md) | @@ -607,7 +644,11 @@ agents see the clone's view, and harvest lands through this merge. Design in | **P33 — Randomized protected encryption** | Close equality confirmation for new protected content | fresh DEK + nonce per seal, dual-read/randomized-write, keyed local stat cache, rewrap upgrade | [0043](docs/adr/0043-randomized-protected-encryption.md) | | **P34 — Private branches** | Keep an entire branch opaque before publication | sealed object closure behind a manifest; O(1) grant, KEK-rotating revoke, scanner-gated publish | [0044](docs/adr/0044-per-branch-access-control.md) | | **P35 — Native desktop browser** | Prove native `.sc` objects can power a polished visual tool | Tauri app opens a repository and browses refs, snapshot DAG/provenance, public trees, and first-parent diffs while locked/private states remain safe | [0045](docs/adr/0045-native-desktop-read-model.md) | +| **P36 — Bucket WAL remotes** | Sync through an object store with no long-lived server | `sc remote add sc+wal://` or `sc+s3:///`; immutable packs plus one CAS'd manifest, checkpoints for cold start (P36b), `sc serve --store ` for a disposable bucket-backed server (P36c); signatures, transcripts and drop tombstones travel (#229); covered by unit and integration tests, no demo script | [0046](docs/adr/0046-wal-bucket-remotes.md) | | **P37a — Want-by-id fetch (`sc cat`)** | Read outside a partial clone's filter without backfilling everything | `sc clone --filter src/ --lazy`; `sc cat main:docs/api/guide.bin` fetches exactly the absent trees and the blob by object id (`GetObjects`, wire v5), sibling untouched; `SC_OFFLINE=1` and non-lazy clones keep the gap error; proven by `demo/run_lazy_fetch_demo.sh` | [0047](docs/adr/0047-want-by-id-fetch-and-gap-fill.md) | +| **P37b — Presence-based partial clones** | Make push, verify, gc and the view agree on what a partial clone holds | `reachable_objects_partial` walks the store, not the filter; `GapInView` before any write; on a lazy, online clone the view closure is filled by id before switch, fast-forward, undo and `sparse set` (which may widen past the filter) | [0048](docs/adr/0048-presence-based-partial-clones.md) | +| **P37c — Merge on partial clones** | `sc merge`, `sc cherry-pick` and `sc rebase` without a full clone | tree-recursive engine carries subtrees by id; conflicts in the view are marked and resolved with `sc conflicts`/`sc resolve`; conflicts outside the view are refused before any write | [0049](docs/adr/0049-merge-on-partial-clones.md) | +| **P37d — Sessions on partial clones** | Agent workspaces on a partial clone | `sc ws fork/run/harvest/abandon` and `sc work` see the clone's sparse view; harvest lands through the ADR-0049 merge, conflicts fall back to `work-` | [0050](docs/adr/0050-sessions-on-partial-clones.md) | > **Prior art.** Phases P5–P9 adapt decisions from the sibling project > [git.agentic](https://github.com/git-agentic/git.agentic) (same BLAKE3 @@ -694,189 +735,68 @@ These apply across phases rather than to one: ## Deferred -Tracked but out of scope for this roadmap horizon (former entries have -graduated twice over: revocation tombstones → P16, bulk re-wrap + escrow -keys → P17, network Git remotes → P18, history-editing polish → P19, -sessions + auto-merge → P20; and now policy-op guards + marks recovery + -abort/status minors → P21, signed commits → P22, merge ergonomics → P23, -sparse checkouts → P24, streaming (>4 GiB) wire frames → P25, sc-native -HTTP transport → P26, and partial clone → P27 — this closes the P25–P27 -scale-&-reach horizon): +Tracked but out of scope for this roadmap horizon. Entries that name an issue +(`#NNN`) mirror the open GitHub issues; the rest have no issue yet. Shipped +items live under Done above, not here. -- **`sc serve --http` connection limits (P26) — shipped in P31 - (ADR-0041).** The three gaps recorded here are closed: a connection cap - (`--max-connections`, default 32), a per-connection idle/session timeout - (`--timeout`, default 300 s, covering the transfer after the opening - read), and bounded accept-loop backoff on repeated accept errors. - **Remaining history-editing depth:** operation objects in the CAS (Jujutsu-deep upgrade to the file oplog), oplog entries for remote-tracking refs. -- **Named/multiple concurrent ws sessions** (P20 ships one unnamed - session per repo) and workspace re-fork/refresh from a newer tip. +- **Named/multiple concurrent ws sessions (#215, P20).** P20 ships one unnamed + session per repo; named or concurrent sessions and workspace re-fork/refresh + from a newer tip need a design decision first. +- **Transcript drop delivery gaps (#230, ADR-0038 addendum).** A tombstone is + not sent after the dropper's gc removed its snapshot, and a tombstone a + push-only remote received before trusting the signer is not re-evaluated + later; both are documented limits, not regressions. +- **Sparse + private-branch and untracked-file edge cases.** #240: a conflicted + merge-in on a private branch under a sparse spec resurrects a file the public + side deleted outside the view. #241: on a case-insensitive filesystem the + untracked-file guard can alias an old-view path with a newly in-view one. + #248: an untracked file at an out-of-view path that the other side adds wins + over the merge result at completion. +- **Abort and private-merge stop bugs.** #246: `--abort` of a merge stopped on a + private branch fails with `WrongKind`, and a binary conflict's `.theirs` + sidecar is committed into the sealed tree. #247: `--abort` of a stopped + merge, pick or rebase fails with `IsADirectory` when the decided root replaced + a file with a directory. +- **Exec-bit review follow-ups (#243, from #242).** Mask setuid/setgid/sticky in + `worktree::write_file`, tests for the protected and private write-out paths, + `sc resolve` after a deleted conflicted file loses the execute bit, and + `vfs::Worktree::checkout` should tolerate `Unsupported` like `write_file`. - **Network-Git same-remote edge cases** (ADR-0018's re-synthesis limitation across different Git repos). -- **Richer trust models** beyond trusted-key lists (delegation, expiry) — - P22 ships the key-list model. -- **Sidecar-cleanup footgun in `rebase_continue` — fixed.** A stop records the - `.theirs` sidecars it actually wrote in `.sc/CONFLICT_SIDECARS`; merge/pick/ - rebase abort, `rebase --continue` and `sc resolve` unlink only those (and - never a path the restored tree tracks), so an untracked user `foo.txt.theirs` - survives whatever the conflict kind. -- **Completion commits a leftover `.theirs` sidecar — fixed.** The completion - snapshot (`sc commit`, `rebase --continue`) leaves out the sidecars the stop - recorded in `.sc/CONFLICT_SIDECARS` unless a root tracks that path, and the - commit then removes them; resolving by hand-editing no longer commits the - scratch file. - Known limit: the sweep retires the record before it unlinks, so a crash - between the two leaves the scratch file on disk with no record, and a retried - `sc commit` would take it. The opposite order would risk deleting a file the - user recreated at that path; closing both needs a journal. -- **In-progress guard for the RECEIVING repo on push — fixed.** - `LocalTransport::update_ref` (so `sc push` to a local path and the wire - `UpdateRef`) refuses to move the receiving repo's checked-out branch while a - merge, cherry-pick or rebase is stopped there (`MergeInProgress` & co.), so - the completing commit cannot silently drop a pushed commit. Other branches - are unaffected. -- **Sparse ergonomics (P24 final-review Minors) — shipped.** `sc sparse set` - warns for each prefix that matches no tracked path at HEAD (the tree is still - laid out, empty, and `sc sparse disable` is named as the way back); a bare - `sc sparse set` on a full clone is refused with a pointer to `sc sparse - disable` (a partial clone keeps its `sc backfill` refusal); and `.sc/sparse` - parsing ignores blank lines. -- **Sparse follow-ups from #210 — shipped (#224).** A partial clone treats a - binary conflict's `.theirs` sidecar as in view when its conflicted path is, so - a file-exact spec no longer refuses it. `sc sparse set` may widen (never - narrow) while a merge, cherry-pick or rebase is stopped: the files coming into - view are laid out from the stop's decided root, so `rebase --continue`'s - out-of-view refusal no longer needs an abort. Protected files that come into - view mid-stop are not decrypted: they stay absent from disk and completion - carries them. A rebase's final fold re-lays the tree and decrypts them with - `--identity`; a merge or cherry-pick finished with `sc commit` writes no - working tree, so they stay absent until the next operation that does (a - `switch`, or `sparse set` again). -- **Transparent lazy-fetch for partial clones (P27).** `sc backfill` is - explicit-only by design (ADR-0037's "no network in read paths" choice); - the identical filtered-walk/gap infra could instead dial the promisor - origin automatically on any gap, matching git's promisor default. Real - scope/risk (offline breakage, surprise latency, fetch-during-gc), so it - stays deferred, not accidentally missing. - **Now scoped as P37 (ADR-0047):** an opt-in `.sc/promisor-lazy` marker over a - batched by-id `GetObjects` verb, keeping `Store::get` network-free. P37a - (`sc cat`) is built; the rest is P37b. -- **Per-case gap-tolerant merge/rebase/ws-harvest/sc-work on a partial - clone (P27).** These are refused entirely today - (`Error::PartialCloneUnsupported`) rather than gap-tolerantly - reimplemented — a deliberate MVP coarsening, not a technical ceiling. - Threading gap-tolerance through `three_way`/replay/`ws::harvest` - individually is the follow-on if the "backfill to a full clone first" - workaround proves too coarse in practice. - **Now scoped as P37b (ADR-0048) and P37c (ADR-0049, Proposed):** push, - verify and gc are presence-based (built); merge is designed in ADR-0049, - with replay and sessions (ADR-0050) following it. -- **Blob-size/object-count clone filters (P27).** `sc clone --filter` is - prefix-only, matching the sparse path-boundary machinery already built; - git's `--filter=blob:limit` size-based filtering is a separate axis, - deferred. -- **Randomized protected mode — SHIPPED in P33 (ADR-0043).** `sc protect` - used to stay convergent (deterministic DEK/nonce per plaintext), so - ciphertext equality confirmed plaintext equality without decryption — - accepted by design in ADR-0014, surfaced by P28's filename nudge. P33 closes - it: all new protected content seals under a fresh random DEK + nonce - (dual-read for pre-P33 convergent history; `sc rewrap` upgrades a tip on - demand). Moved from deferred to Done above. -- **Rotate-for-paths — shipped (ADR-0051).** `sc rewrap --rotate` re-seals every - protected blob at the tip under a fresh DEK (the path analogue of `sc secret - rotate`); history keeps the old ciphertext (rotation is not erasure). +- **Richer signer trust models** beyond trusted-key lists (delegation, expiry) + — P22 ships the key-list model. (Unrelated to serve-token expiry, which + shipped.) +- **Transparent lazy-fetch in read paths (P27, narrowed by P37).** `Store::get` + stays network-free by design (ADR-0037, ADR-0047). What shipped is opt-in: a + lazy clone's `sc cat` and view-filling operations fetch by id, and everything + else reports a gap with the `sc backfill` repair. Dialing the promisor origin + from any read path is still deferred (offline breakage, surprise latency, + fetch-during-gc). +- **Blob-size and object-count clone filters (#217, P27).** `sc clone --filter` + is prefix-only; git's `--filter=blob:limit` size axis needs a decision on the + repair path for a size gap, where the filter is evaluated, and protected + content first. - **`sc rewrap` on partial clones — refused (P37).** `Repo::rewrap` calls `refuse_on_partial`; a paths-only/streaming rebuild that would lift the refusal remains a possible follow-on. -- **Protected-cache hygiene — shipped.** `ProtectedCache::save` skips entries - whose file is no longer on disk (deleted, renamed, outside the sparse view), so - `.sc/protected-cache` and `.sc/ws/cache-` stay bounded by the protected - files actually present; a ws cache file is already removed with its session. - A dropped entry can only cost one re-seal if the path returns (randomized - sealing, so unchanged content gets a new blob id). -- **Theirs-side resolve carry — shipped.** Completion's carry now also checks - the cache against the other parent's blob (merge head or picked commit), so a - `sc resolve --theirs` protected path keeps their ciphertext instead of - re-sealing; their wrap list must be in the unioned protection, and a lookup - gap on a partial clone just seals. - **Non-unix local-key permissions (#214, P33 follow-on).** `.sc/local-key` is minted 0600-from-first-byte on unix only. On a non-unix target it keeps default - permissions and `sc` warns once when a cache holds a protected entry (the - exposure is bounded; see THREAT-MODEL.md). Deferred: an owner-only Windows ACL + permissions and `sc` warns once when a cache holds a protected entry (#225; the + exposure is bounded, see THREAT-MODEL.md). Deferred: an owner-only Windows ACL (`windows-sys` is already in `Cargo.lock`) and a manual check on a real Windows host. -- **fd secret injection — shipped (ADR-0052).** `sc run --secrets-fd N` hands the - secrets to the command on a descriptor (NUL-terminated `NAME=VALUE` records) - instead of its environment. Not built: the same mode for `sc ws run` and +- **fd secret injection beyond `sc run` (ADR-0052 follow-on).** `sc run + --secrets-fd N` shipped. Not built: the same mode for `sc ws run` and `sc work --with-secrets`, and a stdin variant. -- **`--max-object-size` operator knob — shipped (#213, ADR-0039 addendum).** - `sc serve --max-object-size` and `SC_MAX_OBJECT_SIZE` set the per-object cap - (default 256 MiB, range 2 MiB to 1 GiB, out of range aborts startup). No wire - negotiation: each receiver applies its own cap. -- **Per-connection write budget — shipped (#233, ADR-0039 second addendum).** - `sc serve --max-conn-bytes` bounds the sum of `PutObject` bytes and `PutPack` - bytes (per pack, the larger of spool bytes and decoded bytes held) one connection can - make the server retain; over it the server replies - `ConnectionBudgetExceeded` and closes. No `PROTOCOL_VERSION` bump. Not built: - a request-count or CPU budget, and a per-peer (cross-connection) budget. -- **P28 review follow-ons — shipped.** `refs::write_head`/`delete_branch` run - `validate_branch_name`; `SC_PACK_CHUNK` is clamped to the minimum configurable object cap minus one (2 MiB - 1, so every chunk frame fits any valid receiver) (a chunk frame carries a tag byte too; an - oversized value used to make every transfer fail with a confusing receiver - error); `Repo::worktree_paths` is a paths-only walk (`list_worktree_paths`, - the same ignore and tracked-path rules as `read_worktree`, no file read); and - the `/`-boundary rule is one shared `protect::path_under_prefix` used by rule - lookup and the `sc protect` low-entropy nudge. +- **Further serve budgets (ADR-0039 second addendum follow-on).** `--max-conn-bytes` + shipped (#233). Not built: a request-count or CPU budget, and a per-peer + (cross-connection) budget. - **Per-path/per-ref ACLs (P29).** `sc serve --http` access control is all-or-nothing per connection (`ro`/`rw`); scoping a token to specific path prefixes or refs is beyond the MVP. Deferred. -- ~~**Token expiry/rotation metadata (P29).** `sct-` tokens have no expiry - field; rotation today is add-new + remove-old with no automation or - reminder.~~ **Done.** (#209) `sc serve token add --expires <30d|2030-01-31>` - stores an optional `expires_at` (Unix seconds); `verify` treats an expired - token like an unknown one (`401`); `list` shows and flags expiry; `sc serve - token rotate