diff --git a/AGENTS.md b/AGENTS.md index b8fe6cb4..e5908abf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,1301 +1,14 @@ -# AGENTS.md — working guide for src-control +# AGENTS.md -Read this before making changes. It captures what this project is, how it's -structured, and the conventions to keep it coherent over time. +**Read [`CLAUDE.md`](CLAUDE.md) — it is the single working guide for this repo** +(what the project is, crate layout + dependency rule, core invariants, +conventions, commands, and the capability map). -## What this is +This file used to be a full copy of that guide and drifted stale within days +(it froze at Phase 30 while CLAUDE.md moved on). It is now a pointer so that +can never happen again. Do not add content here; edit `CLAUDE.md`. -A next-gen version control system. Long-term thesis: a snapshot-and-tag model -(Jujutsu-inspired) with per-file permissions, native committed secrets, and -in-memory clones. We are **not** replacing Git wholesale — we build on / interop -with Git where it saves time. - -MVP scope is two wedges: -- **Phase 1 (done):** in-memory virtual worktrees for parallel agents, with a - bounded memory budget + eviction, leaving zero residual files on disk. -- **Phase 2 (built):** native committed secrets via envelope encryption, - decrypted only in an authorized execution context. - -Full design is in `ARCHITECTURE.md`; the rationale behind each major decision is -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"). -- **Edition:** 2021, inherited via `[workspace.package]`. -- **Key deps (pin latest stable; no LTS concept in Rust/crates):** - `blake3`, `thiserror`, `hex`, `gix` (Git interop only), `clap`, `anyhow`. - Phase 2 added RustCrypto AEAD (XChaCha20-Poly1305) + X25519 in `crates/crypto`. -- Bump deps with `cargo add`/`cargo update`; do not hand-edit version pins to - guesses. `gix` must keep its **default features** (it needs the `sha1` - hashing feature — disabling defaults breaks `gix-hash`). - -## Workspace layout & dependency rule - -``` -crates/core → content-addressed store, object model, budget + eviction -crates/vfs → in-memory worktree engine (depends on core) -crates/gitio → Git import via gix (depends on core; ONLY crate that links gix) -crates/crypto → envelope encryption (depends on core; ONLY crate linking RustCrypto) -crates/repo → persistent .sc/ repo: objects, refs, branches, working tree (depends on core/vfs/crypto) -crates/cli → `sc` binary (depends on repo + vfs + gitio + crypto + core) -``` - -Strict dependency direction: `cli → repo → {vfs, gitio, crypto} → core`. -**`core` must never depend on Git, worktrees, or crypto.** **`gix` must stay -quarantined in `gitio`** — if you find yourself reaching for `gix` elsewhere, -add a function to `gitio` instead. **RustCrypto must stay quarantined in -`crypto`** — if you find yourself reaching for it elsewhere, add a function to -`crypto` instead. **`repo` must not depend on `gitio`** — `cli` links both and -passes imported snapshots down; `repo` stays Git-agnostic. - -## Core invariants (do not break) - -- **Content addressing:** every object's id is `BLAKE3(canonical_encoding)`. - Encoding is length-prefixed and tree entries are sorted, so the same content - hashes identically on any machine. If you change the encoding, you change all - ids — treat it as a format break and update tests. -- **Blobs are `Arc<[u8]>`-shared.** Forking a worktree must not copy file - content. Don't introduce a code path that deep-copies blob bytes per worktree. -- **Disk invariant is mode-scoped.** - - *Ephemeral mode* (agents, `sc demo`, `sc secret-demo`): disk is touched only - by `Worktree::checkout` and the optional spill backend, both removed on - session teardown. Zero residual files after the session ends — this is the - whole Phase 1 pitch. Guard it. Verified by `sc demo` and `demo/run_demo.sh`. - - *Persistent mode* (`sc init` repos): disk writes to `.sc/` by design. - `.sc/` is user-owned durable state (like `.git/`). Every `Store::put` in - persistent mode writes to `.sc/objects/`; `switch` materializes the working - tree; `commit` snapshots it. This is correct and expected behavior. - The two modes compose in exactly one way: a `sc work` session (P13) is a - bounded ephemeral session *hosted by* a persistent repo — temp checkouts - are removed on teardown, and the only durable writes go through the same - commit path persistent mode already owns. Otherwise a session is either - ephemeral or persistent, never a mix. -- **Memory budget bounds resident blob bytes.** Trees/snapshots/secrets stay - resident (small) and are not evicted. Only reconstructible blobs are evictable. - Dirty overlay writes are pinned in the worktree and never spilled. -- **Without spill, over-budget inserts fail loudly** (`Error::BudgetExceeded`). - Never silently drop data to stay under budget. - -## Conventions - -- Every public type/fn gets a doc comment explaining intent, not mechanics. -- Errors: per-crate `thiserror` enums; the CLI uses `anyhow`. Convert with `?` - (a bare `return some_vfs_result;` won't coerce into `anyhow::Error`). -- Tests live in `#[cfg(test)] mod tests` next to the code. Every new behavior - ships with a test. Tests that materialize to disk must clean up after - themselves and assert the path is gone. -- Keep the CLI demo (`sc demo`) honest: it must end by proving zero residue, and - `demo/run_demo.sh` provides an independent before/after filesystem diff. - -## Commands - -```sh -cargo test # whole workspace -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 -- 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 - # encryption key and an Ed25519 signing key (P22); - # a pre-P22 v1 (scl-sk-) identity still parses and - # still encrypts, but cannot sign -cargo run --bin sc -- secret-demo # committed-secrets authorize/deny/grant proof - -# Persistent repo commands (sc init creates .sc/ in the working directory): -cargo run --bin sc -- init # initialize a new persistent repo -cargo run --bin sc -- commit -m "msg" # snapshot working tree as a commit - # honors .scignore at the repo root (gitignore - # subset; hides untracked matches only — tracked - # paths are never ignored) -cargo run --bin sc -- status # working-tree changes vs HEAD (--json for scripts) -cargo run --bin sc -- diff # line-level unified diff vs HEAD -cargo run --bin sc -- log # history: id, date, author, message, (merge) marker - # (--json for scripts; also on secret list) - # commit/merge author: --author > $SC_AUTHOR > OS user -cargo run --bin sc -- branch # create a new branch at current tip -cargo run --bin sc -- switch # switch branch + materialize working tree -cargo run --bin sc -- merge [--identity ] # three-way merge (ff when possible; exits - # 1 on conflicts; --identity only needed when a - # protected path diverged in content on both sides) -cargo run --bin sc -- conflicts [] [--identity ] [--json] - # no path: lists conflicted paths + kind (text/ - # binary/protected); with path: base/ours/theirs, - # decrypted under --identity for protected paths (P23) -cargo run --bin sc -- resolve --ours|--theirs ... [--identity ] - # writes the chosen side's clean content, drops - # sidecars, clears the path from the active - # 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 -- grant --to --identity # path-protection grant -cargo run --bin sc -- revoke --recipient-id # path-protection revoke; - # tombstone-durable across merges of pre-revoke - # branches (P16) - # NB: top-level grant/revoke act on protected - # path prefixes; `secret grant/revoke` act on - # named secrets — two different surfaces -cargo run --bin sc -- secret add --to --value - # omit --value to read the secret from stdin - # (keeps it out of `ps` and shell history); - # `secret rotate --value-stdin` likewise -cargo run --bin sc -- secret grant --to --identity -cargo run --bin sc -- secret revoke --recipient-id -cargo run --bin sc -- secret list -cargo run --bin sc -- run -- [args…] # inject decrypted secrets + run command -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 --include-encrypted # allow protected ciphertext -bash demo/run_repo_demo.sh # end-to-end persistent repo proof -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) -bash demo/run_git_remote_demo.sh # git-as-a-remote round-trip proof -cargo run --bin sc -- remote add ssh://[user@]host[:port]/path # ssh-native remote -cargo run --bin sc -- clone ssh://host/path # clone over ssh (spawns `ssh … sc serve --stdio`) -cargo run --bin sc -- serve --stdio # wire-protocol server (invoked via ssh; not interactive) -bash demo/run_ssh_remote_demo.sh # ssh transport round-trip proof (SC_SSH shim, no sshd) -cargo run --bin sc -- secret rotate --value # re-seal under a fresh DEK -cargo run --bin sc -- secret rotate --identity # same value, fresh DEK -cargo run --bin sc -- escrow set # break-glass recovery key - # (replace-with-one sugar, P17) -bash demo/run_lifecycle_demo.sh # rotation + escrow proof -cargo run --bin sc -- rewrap [--identity ] [--dry-run] # one-commit bulk reseal of all - # secrets + protected wrap lists to current - # recipient/escrow sets (skip-and-report; - # exits 1 when entries were skipped) -cargo run --bin sc -- escrow add # append a break-glass key (list) -cargo run --bin sc -- escrow remove -cargo run --bin sc -- escrow show # lists all escrow keys -bash demo/run_rewrap_demo.sh # bulk rewrap + escrow-list proof -cargo run --bin sc -- work --agents 3 -- # fork agent workspaces, run in each, - # harvest changed ones to work- branches - # (--with-secrets --identity injects - # decrypted secrets into each agent env) -bash demo/run_work_demo.sh # parallel-agents round-trip proof -cargo run --bin sc -- ws fork --agents N [--identity ] # durable multi-invocation - # session: materializes N checkouts under - # .sc/ws// and persists a manifest (P20) -cargo run --bin sc -- ws list # open session's workspaces, changed/unchanged -cargo run --bin sc -- ws run [--with-secrets --identity ] -- # run in - # workspace i (SC_WORKSPACE/SC_WORKSPACE_DIR set) -cargo run --bin sc -- ws harvest [--into ] [--identity ] # probe + auto-merge - # 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- -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 - # current branch (--identity as above) -cargo run --bin sc -- cherry-pick --mainline # replay a merge commit relative - # to its Nth (1-indexed) parent; required for - # merge commits, refused on non-merges (P19) -cargo run --bin sc -- cherry-pick --abort # abandon a stopped pick; restores the - # untouched tip (no oplog record — no ref - # ever moved) (P19) -cargo run --bin sc -- rebase [--identity ] # replay current branch onto - # ; a conflict STOPS (not aborts) with - # persisted state — resolve then --continue - # (default since P19; --identity as above) -cargo run --bin sc -- rebase --continue [--identity ] # resume a stopped rebase; - # any number of stops still collapses into ONE - # oplog record / ONE undo (P19) -cargo run --bin sc -- rebase --abort # abandon a stopped rebase; restores the - # pre-rebase working tree (P19) -cargo run --bin sc -- amend [-m ] # rebuild the tip from the working tree, tip's - # own parents kept, message kept unless -m (P19) -cargo run --bin sc -- undo # revert the last operation (again = redo) -cargo run --bin sc -- oplog # list recent operations -bash demo/run_history_demo.sh # cherry-pick/rebase/undo round-trip proof -bash demo/run_protected_merge_demo.sh # protected merge & replay proof (P15) -bash demo/run_revoke_demo.sh # revocation-tombstone durability proof (P16) -cargo run --bin sc -- clone [--git] # auto-detects hosted-git URL forms - # (https://, http://, scp-style git@host:path, - # file://) and routes through the git mirror - # bridge (P18); bare ssh:// stays sc-native (P12) - # unless --git forces the mirror path; network - # forms require git on PATH (SC_GIT to override - # the binary) -cargo run --bin sc -- remote add --git # --git also accepts network URL forms - # (https://, http://, scp-style, ssh://) as of - # P18, alongside P10's local .git paths; --git - # stays required in every case; network forms - # require git on PATH (SC_GIT to override) -bash demo/run_network_git_demo.sh # hosted-git round trip over file:// (P18; prints - # the real-GitHub recipe: sc remote add origin - # git@github.com:… --git) -cargo run --bin sc -- commit -m "msg" --sign [--identity ] # sign the new tip (P22; - # requires a v2 identity — see `sc keygen`) -cargo run --bin sc -- amend [-m ] --sign [--identity ] # sign the amended tip (P22) -cargo run --bin sc -- sign [--identity ] # retroactively sign any ref's tip - # snapshot (P22; also the MVP path for signing a - # merge/pick/rebase result — re-sign after) -cargo run --bin sc -- verify [] [--require] # walk history (all parents, not just - # mainline), report each commit's signature - # status (trusted ✓ / untrusted ? / INVALID ✗ / - # unsigned); --require exits 1 unless every - # commit is trusted (P22) -cargo run --bin sc -- transcript attach [--agent ] [--sign] [--identity ] - # seal an agent-session transcript (P30) and attach - # it to 's tip; body sealed to the full - # [recipients] set + escrow — plaintext never enters - # the CAS (keyless clone gets ciphertext only); - # --sign attests the transcript id (opt-in) -cargo run --bin sc -- transcript show [--identity ] # decrypt + print a tip's - # transcripts (needs --identity) -cargo run --bin sc -- transcript list [] [--json] # list transcripts (never decrypts) -cargo run --bin sc -- transcript sign [--identity ] # retroactively sign a tip's - # transcript(s) (P30) -cargo run --bin sc -- ws harvest --transcript [--sign] [--identity ] # attach the - # file to each harvested workspace's landed snapshot - # (P30; landing status prints before the attach) -bash demo/run_transcript_demo.sh # session-transcript proof (P30): attach --sign, - # clone rides the pack, keyless clone = ciphertext, - # identity decrypts byte-exact, sc log marker, gc - # prunes a transcript with its dead snapshot -bash demo/run_provenance_demo.sh # signed-history + rewrite-attack proof (P22): - # alice signs, clone verifies clean, `sc amend` - # in the clone is caught by `sc verify --require` - # while the original stays clean, bob's - # retroactive `sc sign` shows ? until trusted -bash demo/run_merge_ergonomics_demo.sh # sc conflicts/sc resolve proof (P23): a text - # conflict and a protected (identity-decrypted) - # conflict both resolved end-to-end with no - # hand-edited markers -cargo run --bin sc -- sparse set [--identity ] # narrow the working tree to - # these path prefixes; re-lays disk now (P24) -cargo run --bin sc -- sparse show [--json] # list the active sparse prefixes ("disabled" if - # the spec is empty/absent) (P24) -cargo run --bin sc -- sparse disable [--identity ] # clear the spec and rematerialize - # every subtree in full (P24) -bash demo/run_sparse_demo.sh # sparse checkout proof (P24): narrow to one of - # three subtrees, edit + commit under sparse, then - # sc sparse disable AND an independent full clone - # both restore the other two byte-identical -bash demo/run_streaming_demo.sh # streaming pack transfer proof (P25): a forced - # SC_PACK_CHUNK=4096 crosses a ~1 MiB signed blob - # in 250+ chunk frames, byte-for-byte clone, zero - # .sc/tmp residue on either end -cargo run --bin sc -- serve --http [--read-only] [--allow-public] - # sc-native wire protocol over TCP (P26); e.g. - # `sc serve --http 127.0.0.1:8730 .`; exactly one - # of --stdio/--http is required; a non-loopback - # is refused unless --read-only, - # --allow-public, or a configured serve token - # justifies it (P29) -cargo run --bin sc -- serve token add --label --scope ro|rw # mint an - # sct- bearer token in .sc/serve-tokens.toml; - # raw value prints once on stdout (P29) -cargo run --bin sc -- serve token remove