feat(clone): copy shallow boundaries from a local Git source

COMPATIBILITY.md

@@ -161,7 +161,7 @@ there is no promised all-phase 30-second hard deadline. See
 | Command | Tier | Notes |
 |---------|------|-------|
 | init | partial | common initialization plus Git-style safe re-initialization/top-up of an existing repo (prints `Reinitialized existing ...`, re-creates missing layout, re-applies `--shared`, persists `core.sharedRepository`, preserves config/HEAD/refs/objects/vault/repo-id otherwise) are supported; when `-b/--initial-branch` is omitted for a new repo, `init.defaultBranch` is read local→global→system with case-insensitive variable matching, local/global encrypted values decrypted, and `main` fallback; empty/invalid values fail before layout with `LBR-CLI-002`, local/global config DB read failures use `LBR-IO-001` (except a future-schema global store — newer than this binary — which is skipped with a one-time warning, see `LBR-CONFIG-001`), and unreadable/unsupported system scope is skipped; `--from-git-repository` reports the source `HEAD` branch instead of applying the configured default; numeric `--shared=<mode>` is prevalidated so non-traversable modes such as `0660` fail before a partial `.libra` is created; recursive submodule init is not; the per-user Libra home and global config directory are reserved: init refuses them as storage roots, discovery skips stray home databases (including commondir targets), and opening an older database restores a missing legacy config table without deleting existing configuration (#472) |
-| clone | partial | `--depth`, `--single-branch`/`--no-single-branch` (toggle; `--no-single-branch` countermands `--single-branch`, last wins, and clone fetches all branches by default so `--no-single-branch` alone is a no-op), `--tags`/`--no-tags` (clone fetches all tags by default like Git; `--no-tags` skips them and records `remote.<name>.tagOpt=--no-tags`, where `<name>` is the remote name — `origin` by default or the `-o`/`--origin` value), and `--no-progress` (suppresses the fetch "Receiving objects" progress meter during the clone, like `git clone --no-progress`), `--no-checkout` (set up objects/refs/HEAD but do not check out the working tree), and `-o`/`--origin <name>` (name the remote and its tracking refs instead of `origin`; standard clones only), `-l`/`--local` and `--no-local` (accepted no-ops — Libra never hardlinks objects (it always copies), and how it reads a local-path source is determined by the source type — a local Libra repo is read directly, a local Git repo is read in-process (no `git-upload-pack` dependency) — not by these flags), and `--reject-shallow` (fail when the clone is shallow without `--depth`, i.e. a shallow source — exit 128; `--depth` is allowed and, as a documented narrowing vs Git, suppresses the check since Libra cannot distinguish a shallow source from `--depth`-induced shallowness), and the object-alternates flags: `--shared`/`-s` (lore.md 2.11 — for a LOCAL Libra source, registers the source's object store as an alternate of the clone via lore.md 2.3's guarded path: borrowed reads + base gc/evict/obliterate protection; NON-FATAL on any guard/io failure — the clone still succeeds; v1 STILL COPIES every object, so this only adds the borrow link + base protection, NOT disk savings — copy-avoidance is deferred; a no-op warning for a remote/local-Git source), `--no-shared` (countermands `--shared` / a `clone.shared=true` default), the `clone.shared` config (global default; default OFF), `--dissociate` (forces no-share — a self-contained clone), and `--reference <repo>`/`--reference-if-able <repo>` (still accepted no-ops — Libra has no fetch-side alternate negotiation yet, so `--reference` copies + warns and `--reference-if-able` is silently ignored; use `libra alternates add` to borrow), and `--mirror` (implies `--bare`; maps every fetched branch verbatim into `refs/heads/*` and keeps tags, drops the `refs/remotes/*` tracking refs, and records the `remote.<name>.mirror=true` marker. Documented narrowings: Libra mirrors only what it fetches — `refs/notes/*` and other un-fetched namespaces are not mirrored, and because fetch collapses `refs/mr/*` into the branch tracking namespace those refs are mirrored as `refs/heads/mr/*`; the marker is informational since `libra fetch` is not yet mirror-aware, so no `+refs/*:refs/*` refspec is recorded), and the fetch-optimization flags `--filter <spec>`/`--shallow-since <date>`/`--shallow-exclude <rev>` (accepted no-ops for Git remotes — Libra has no partial-clone/promisor support and its fetch only does `--depth` shallow, so each is ignored with a warning and the optimization is simply not applied — the clone fetches everything those flags would trim, subject only to `--depth` if also given (without `--depth`, a complete clone, a correct superset), matching Git's own full-clone fallback when a server cannot filter), and the dependency-filtered clone flags `--deps-of <path>` (repeatable) / `--deps-depth-limit <N>` (lore.md 3.2, intentionally-different — Git has no file-dependency concept; NOT partial-clone/`--filter` and NOT `--sparse`/D10): after a normal FULL, commit-safe checkout, scope the read-only sparse VIEW (2.2) to the forward dependency closure (3.1) of the given roots and record `remote.<name>.fetchNotesDeps=true`; implies `--notes` (the graph is fetched to compute the closure). Objects are NEVER wire-filtered — the whole pack is downloaded and the whole tree stays on disk (working-tree disk narrowing is deferred, D18); only a local Libra source can travel the graph (D17), a network/foreign-Git remote performs a full clone without scoping and warns; conflicts with `--no-checkout`/`--bare`/`--mirror` supported; `--sparse` unsupported (see [docs/development/commands/_compatibility.md#d10-clone---sparse-与顶层-sparse-checkout-命令](docs/development/commands/_compatibility.md#d10-clone---sparse-与顶层-sparse-checkout-命令)); `--recurse-submodules` unsupported (see [docs/development/commands/_compatibility.md#d4-clone---recurse-submodules](docs/development/commands/_compatibility.md#d4-clone---recurse-submodules)) checked-out entries carry the tree mode's permission bits (`100755` executable, `100644` plain) under the process `umask`, and replacing an existing file clears a stale execute bit (plan issues/470 FM-01, ADR-FM-02). A local Git source via `file://` or `--no-local` truncates by shortest distance from any want, then one boundary pass (a missing parent, or a root exactly on the depth cutoff, is written to `.libra/shallow`; issues/474 CL-04). `--depth` / `--shallow-since` / `--shallow-exclude` imply `--single-branch` unless `--no-single-branch` or `--mirror`; that clone writes `remote.<name>.fetch=+refs/heads/<branch>:refs/remotes/<name>/<branch>` (issues/474 CL-05). A plain filesystem Git path ignores `--depth` / `--shallow-since` / `--shallow-exclude` / `--filter` and prints Git's local-clone warnings (`--quiet` still warns); `file://` and `--no-local` keep transport shallow semantics (issues/474 CL-06). |
+| clone | partial | `--depth`, `--single-branch`/`--no-single-branch` (toggle; `--no-single-branch` countermands `--single-branch`, last wins, and clone fetches all branches by default so `--no-single-branch` alone is a no-op), `--tags`/`--no-tags` (clone fetches all tags by default like Git; `--no-tags` skips them and records `remote.<name>.tagOpt=--no-tags`, where `<name>` is the remote name — `origin` by default or the `-o`/`--origin` value), and `--no-progress` (suppresses the fetch "Receiving objects" progress meter during the clone, like `git clone --no-progress`), `--no-checkout` (set up objects/refs/HEAD but do not check out the working tree), and `-o`/`--origin <name>` (name the remote and its tracking refs instead of `origin`; standard clones only), `-l`/`--local` and `--no-local` (accepted no-ops — Libra never hardlinks objects (it always copies), and how it reads a local-path source is determined by the source type — a local Libra repo is read directly, a local Git repo is read in-process (no `git-upload-pack` dependency) — not by these flags), and `--reject-shallow` (fail when the clone is shallow without `--depth`, i.e. a shallow source — exit 128; `--depth` is allowed and, as a documented narrowing vs Git, suppresses the check since Libra cannot distinguish a shallow source from `--depth`-induced shallowness), and the object-alternates flags: `--shared`/`-s` (lore.md 2.11 — for a LOCAL Libra source, registers the source's object store as an alternate of the clone via lore.md 2.3's guarded path: borrowed reads + base gc/evict/obliterate protection; NON-FATAL on any guard/io failure — the clone still succeeds; v1 STILL COPIES every object, so this only adds the borrow link + base protection, NOT disk savings — copy-avoidance is deferred; a no-op warning for a remote/local-Git source), `--no-shared` (countermands `--shared` / a `clone.shared=true` default), the `clone.shared` config (global default; default OFF), `--dissociate` (forces no-share — a self-contained clone), and `--reference <repo>`/`--reference-if-able <repo>` (still accepted no-ops — Libra has no fetch-side alternate negotiation yet, so `--reference` copies + warns and `--reference-if-able` is silently ignored; use `libra alternates add` to borrow), and `--mirror` (implies `--bare`; maps every fetched branch verbatim into `refs/heads/*` and keeps tags, drops the `refs/remotes/*` tracking refs, and records the `remote.<name>.mirror=true` marker. Documented narrowings: Libra mirrors only what it fetches — `refs/notes/*` and other un-fetched namespaces are not mirrored, and because fetch collapses `refs/mr/*` into the branch tracking namespace those refs are mirrored as `refs/heads/mr/*`; the marker is informational since `libra fetch` is not yet mirror-aware, so no `+refs/*:refs/*` refspec is recorded), and the fetch-optimization flags `--filter <spec>`/`--shallow-since <date>`/`--shallow-exclude <rev>` (accepted no-ops for Git remotes — Libra has no partial-clone/promisor support and its fetch only does `--depth` shallow, so each is ignored with a warning and the optimization is simply not applied — the clone fetches everything those flags would trim, subject only to `--depth` if also given (without `--depth`, a complete clone, a correct superset), matching Git's own full-clone fallback when a server cannot filter), and the dependency-filtered clone flags `--deps-of <path>` (repeatable) / `--deps-depth-limit <N>` (lore.md 3.2, intentionally-different — Git has no file-dependency concept; NOT partial-clone/`--filter` and NOT `--sparse`/D10): after a normal FULL, commit-safe checkout, scope the read-only sparse VIEW (2.2) to the forward dependency closure (3.1) of the given roots and record `remote.<name>.fetchNotesDeps=true`; implies `--notes` (the graph is fetched to compute the closure). Objects are NEVER wire-filtered — the whole pack is downloaded and the whole tree stays on disk (working-tree disk narrowing is deferred, D18); only a local Libra source can travel the graph (D17), a network/foreign-Git remote performs a full clone without scoping and warns; conflicts with `--no-checkout`/`--bare`/`--mirror` supported; `--sparse` unsupported (see [docs/development/commands/_compatibility.md#d10-clone---sparse-与顶层-sparse-checkout-命令](docs/development/commands/_compatibility.md#d10-clone---sparse-与顶层-sparse-checkout-命令)); `--recurse-submodules` unsupported (see [docs/development/commands/_compatibility.md#d4-clone---recurse-submodules](docs/development/commands/_compatibility.md#d4-clone---recurse-submodules)) checked-out entries carry the tree mode's permission bits (`100755` executable, `100644` plain) under the process `umask`, and replacing an existing file clears a stale execute bit (plan issues/470 FM-01, ADR-FM-02). A local Git source via `file://` or `--no-local` truncates by shortest distance from any want, then one boundary pass (a missing parent, or a root exactly on the depth cutoff, is written to `.libra/shallow`; issues/474 CL-04). `--depth` / `--shallow-since` / `--shallow-exclude` imply `--single-branch` unless `--no-single-branch` or `--mirror`; that clone writes `remote.<name>.fetch=+refs/heads/<branch>:refs/remotes/<name>/<branch>` (issues/474 CL-05). A plain filesystem Git path ignores `--depth` / `--shallow-since` / `--shallow-exclude` / `--filter` and prints Git's local-clone warnings (`--quiet` still warns); `file://` and `--no-local` keep transport shallow semantics (issues/474 CL-06). A local Git shallow source is cloned with its `.git/shallow` boundaries merged into `.libra/shallow`; `--reject-shallow` inspects the source before creating the destination and leaves no residual (issues/474 CL-07). |
 | automation | intentionally-different | Libra AI automation rules/history extension, not a Git command. Linked worktrees load `automations.toml` through the unified resolver and dispatch VCS events there; damaged/unreadable scope still fail-closes. |
 | sandbox | intentionally-different | Libra AI sandbox diagnostics extension, not a Git command |
 | cache | intentionally-different | Diagnostic for the tiered-storage / LRU cache (`cache info`): reports the resolved `LIBRA_STORAGE_TYPE`, whether a durable tier is active, and the `LIBRA_STORAGE_THRESHOLD` (small/large threshold) + `LIBRA_STORAGE_CACHE_SIZE` (LRU disk budget) tunables. Git has no equivalent; needs no repository. `--json`/`--machine` → `{ storage_type, tiered, threshold_bytes, cache_size_bytes }`. Exit 0 (non-zero if a storage config value cannot be resolved, e.g. an unreadable global config DB); `cache evict [--dry-run] [--max-size <bytes>] [--min-age <secs>]` (lore.md 2.9): evicts verified-durable LARGE loose objects oldest-first until under the configured budget — every unlink is gated on an error-aware durability probe run immediately before it (confirmed-absent objects are skipped with a push hint; probe ERRORS are never treated as absence; 3 leading probe failures abort with nothing deleted); presence≠integrity residual documented; tiered `get` now self-heals a vanished local file from the durable tier; local-only repos report nothing-evictable; offline read policy refuses; also runnable as `maintenance run --task cache-evict` (excluded from the default task set) — and `maintenance loose-objects` no longer packs >=threshold cache residents under a tiered config |

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libra"
-version = "0.23.52"
+version = "0.23.53"
 edition = "2024"
 license = "MIT"
 description = "AI agent-native version control system with Git on-disk compatibility, SQLite-backed metadata, and tiered cloud storage"

docs/commands/clone.md

@@ -202,19 +202,15 @@ libra clone --depth 50 git@github.com:user/repo.git
 
 ### `--reject-shallow`
 
-Fail if the clone would be a shallow repository that you did not request — i.e.
-the source repository is shallow — matching `git clone --reject-shallow`
-(exit 128). Combining it with `--depth` is allowed only for transports that can
-negotiate shallow boundaries. A local Libra source rejects `--depth` before
-object transfer, and no initialized target is left behind.
-
-Two narrowings vs Git: (1) Libra's clone of a local-path source re-fetches the
-full history rather than inheriting the source's shallow marker, so this check
-is most meaningful when cloning a shallow *remote*; (2) because Libra cannot
-distinguish a shallow source from `--depth`-induced shallowness, passing
-`--depth` suppresses the post-fetch `--reject-shallow` check for remotes that
-do support shallow negotiation (Git would still reject a shallow source with
-`--depth`).
+Fail if the **source** repository is shallow — matching `git clone --reject-shallow`
+(exit 128) — and leave no destination directory behind. A local Git shallow
+source is inspected before the destination is created. Cloning a shallow Git
+source without this flag copies the source's `.git/shallow` boundaries into
+`.libra/shallow` so `log` / `fsck` stay walkable. A local Libra source with
+`--depth` still fails closed with `LBR-REPO-002` before object transfer.
+
+For network remotes that negotiate shallow boundaries, a post-fetch check still
+rejects an unexpected shallow result when `--depth` was not requested.
 
 ```bash
 libra clone --reject-shallow git@github.com:user/repo.git

docs/commands/zh-CN/clone.md

@@ -122,9 +122,9 @@ libra clone --depth 50 git@github.com:user/repo.git
 
 ### `--reject-shallow`
 
-若克隆结果是你未请求的浅仓库（即源仓库本身是浅克隆），则失败，对齐 `git clone --reject-shallow`（exit 128）。只有在传输层能协商 shallow boundary 时，才允许与 `--depth` 同用；本地 Libra 源会在对象传输前拒绝 `--depth`，且不会留下已初始化的目标仓库。
+若**源**仓库是浅克隆则失败，对齐 `git clone --reject-shallow`（exit 128），且不留下目标目录。本地 Git 浅源在创建目标前检查；不带该标志克隆浅源时，会把源的 `.git/shallow` 边界并入 `.libra/shallow`，使 `log` / `fsck` 可遍历。本地 Libra 源带 `--depth` 仍在对象传输前以 `LBR-REPO-002` fail-closed。
 
-相对 Git 的两点收窄：(1) Libra 克隆本地路径源时会重取完整历史、不继承源的浅标记，故该检查主要在克隆浅 *remote* 时有意义；(2) 由于 Libra 无法区分“源是浅克隆”与“`--depth` 导致的浅克隆”，对支持 shallow 协商的远程，给出 `--depth` 会抑制 fetch 后的 `--reject-shallow` 检查（Git 即便带 `--depth` 也会拒绝浅源）。
+对能协商 shallow boundary 的网络远程，未请求 `--depth` 时仍会在 fetch 后拒绝意外的浅结果。
 
 ```bash
 libra clone --reject-shallow git@github.com:user/repo.git