hologit 0.50.2 → 0.50.3

package/holo-tree/tests/write_child.rs

@@ -0,0 +1,281 @@
+//! Regression: writing a child into a subtree that already exists in the
+//! parent commit must load that subtree's existing children (preserving
+//! siblings) rather than panic on `children.as_mut().unwrap()`.
+//!
+//! Surfaced by the gitsheets holo-tree spike (JarvusInnovations/gitsheets#127):
+//! every upsert into an already-populated sheet directory hit this. Before the
+//! fix, `get_or_create_subtree` left the final (lazily-loaded) node's
+//! `children` as `None`, so `write_child_bytes` panicked — aborting the host
+//! process when called across the napi FFI boundary.
+
+mod helpers;
+
+use helpers::Sandbox;
+use holo_tree::MutableTree;
+
+#[test]
+fn write_child_into_existing_subtree_preserves_siblings() {
+    let sb = Sandbox::new();
+
+    // A committed tree that already contains data/a.toml.
+    let base = sb.write_tree(&[("data/a.toml", "id = 1\n")]);
+
+    // Load it lazily and write a sibling into the existing data/ directory.
+    let mut tree = MutableTree::new(base);
+    tree.write_child(&sb.repo, "data/b.toml", "id = 2\n").unwrap();
+    let new_hash = tree.write(&sb.repo).unwrap();
+    assert_ne!(new_hash, base, "writing a child must change the tree hash");
+
+    // Round-trip through the ODB: both records are present.
+    let mut reloaded = MutableTree::new(new_hash);
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "data/a.toml").unwrap().as_deref(),
+        Some(&b"id = 1\n"[..]),
+        "existing sibling must be preserved",
+    );
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "data/b.toml").unwrap().as_deref(),
+        Some(&b"id = 2\n"[..]),
+        "newly written child must be present",
+    );
+}
+
+#[test]
+fn write_child_into_fresh_subtree_still_works() {
+    let sb = Sandbox::new();
+
+    // Empty starting point — the subtree is created fresh.
+    let mut tree = MutableTree::empty();
+    tree.write_child(&sb.repo, "data/only.toml", "id = 1\n").unwrap();
+    let hash = tree.write(&sb.repo).unwrap();
+
+    let mut reloaded = MutableTree::new(hash);
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "data/only.toml").unwrap().as_deref(),
+        Some(&b"id = 1\n"[..]),
+    );
+}
+
+/// Regression: writing a file at the REPO ROOT (dir = ".") into a lazily-loaded
+/// tree must load the root's children rather than panic on
+/// `children.as_mut().unwrap()`. The earlier fix only covered deep paths; the
+/// `path == "."` early-return in get_or_create_subtree bypassed it. Surfaced by
+/// install-testing the published binding with a root-level `writeChild`.
+#[test]
+fn write_child_at_repo_root_preserves_siblings() {
+    let sb = Sandbox::new();
+
+    // Committed tree with a root-level file; reload it lazily (children: None).
+    let base = sb.write_tree(&[("existing.toml", "id = 0\n")]);
+    let mut tree = MutableTree::new(base);
+
+    tree.write_child(&sb.repo, "new.toml", "id = 1\n").unwrap();
+    let hash = tree.write(&sb.repo).unwrap();
+    assert_ne!(hash, base, "a root-level write must change the tree hash");
+
+    let mut reloaded = MutableTree::new(hash);
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "existing.toml").unwrap().as_deref(),
+        Some(&b"id = 0\n"[..]),
+        "existing root sibling must be preserved",
+    );
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "new.toml").unwrap().as_deref(),
+        Some(&b"id = 1\n"[..]),
+    );
+}
+
+#[test]
+fn write_child_at_repo_root_into_empty() {
+    let sb = Sandbox::new();
+    let mut tree = MutableTree::empty();
+    tree.write_child(&sb.repo, "only.toml", "id = 1\n").unwrap();
+    let hash = tree.write(&sb.repo).unwrap();
+
+    let mut reloaded = MutableTree::new(hash);
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "only.toml").unwrap().as_deref(),
+        Some(&b"id = 1\n"[..]),
+    );
+}
+
+/// Regression: deleting a child deep inside a lazily-loaded tree must dirty the
+/// ancestor chain, or `write()` short-circuits on a clean root and silently
+/// drops the deletion (returns the original tree hash). Surfaced by the
+/// gitsheets migration (#127): every Sheet delete/rename-cleanup hit this once
+/// the working tree was binding-backed.
+#[test]
+fn delete_child_deep_into_existing_tree_persists() {
+    let sb = Sandbox::new();
+
+    // Committed tree with two records in a directory; reload it lazily.
+    let base = sb.write_tree(&[("data/a.toml", "id = 1\n"), ("data/b.toml", "id = 2\n")]);
+    let mut tree = MutableTree::new(base);
+
+    let deleted = tree.delete_child_deep(&sb.repo, "data/a.toml").unwrap();
+    assert!(deleted, "the record existed and should report deleted");
+
+    let new_hash = tree.write(&sb.repo).unwrap();
+    assert_ne!(new_hash, base, "deletion must change the tree hash (the bug: it didn't)");
+
+    let mut reloaded = MutableTree::new(new_hash);
+    assert!(
+        reloaded.read_blob(&sb.repo, "data/a.toml").unwrap().is_none(),
+        "deleted record must be gone after write()",
+    );
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "data/b.toml").unwrap().as_deref(),
+        Some(&b"id = 2\n"[..]),
+        "sibling must be preserved",
+    );
+}
+
+/// Deleting a non-existent deep path is a clean no-op: returns false and leaves
+/// the tree hash unchanged.
+#[test]
+fn delete_child_deep_missing_is_noop() {
+    let sb = Sandbox::new();
+    let base = sb.write_tree(&[("data/a.toml", "id = 1\n")]);
+    let mut tree = MutableTree::new(base);
+
+    assert!(!tree.delete_child_deep(&sb.repo, "data/missing.toml").unwrap());
+    assert_eq!(tree.write(&sb.repo).unwrap(), base, "no-op delete must not change the hash");
+}
+
+// ── write_child_hash (#477): place an existing blob by hash ─────────────────
+
+/// Placing a blob by hash yields a byte-identical tree to writing the same
+/// content via `write_child_bytes` — the whole point is to skip re-hashing while
+/// producing exactly the same result.
+#[test]
+fn write_child_hash_matches_write_child_bytes() {
+    let sb = Sandbox::new();
+    let content = b"attachment payload\n";
+    let blob = sb.repo.write_blob(content).unwrap().detach();
+
+    let mut by_bytes = MutableTree::empty();
+    by_bytes
+        .write_child_bytes(&sb.repo, "data/att.bin", content)
+        .unwrap();
+    let bytes_hash = by_bytes.write(&sb.repo).unwrap();
+
+    let mut by_hash = MutableTree::empty();
+    by_hash
+        .write_child_hash(&sb.repo, "data/att.bin", blob, 0o100644)
+        .unwrap();
+    let hash_hash = by_hash.write(&sb.repo).unwrap();
+
+    assert_eq!(
+        hash_hash, bytes_hash,
+        "place-by-hash must produce the same tree as write-by-content",
+    );
+}
+
+/// Placing a blob by hash into an already-populated, lazily-loaded subtree
+/// preserves the existing siblings (same subtree-loading path as
+/// `write_child_bytes`).
+#[test]
+fn write_child_hash_preserves_siblings() {
+    let sb = Sandbox::new();
+    let base = sb.write_tree(&[("data/a.toml", "id = 1\n")]);
+    let blob = sb.repo.write_blob(b"id = 2\n").unwrap().detach();
+
+    let mut tree = MutableTree::new(base);
+    tree.write_child_hash(&sb.repo, "data/b.toml", blob, 0o100644)
+        .unwrap();
+    let new_hash = tree.write(&sb.repo).unwrap();
+    assert_ne!(new_hash, base);
+
+    let mut reloaded = MutableTree::new(new_hash);
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "data/a.toml").unwrap().as_deref(),
+        Some(&b"id = 1\n"[..]),
+        "existing sibling must be preserved",
+    );
+    assert_eq!(
+        reloaded.read_blob(&sb.repo, "data/b.toml").unwrap().as_deref(),
+        Some(&b"id = 2\n"[..]),
+        "placed-by-hash blob must be present",
+    );
+}
+
+/// The `mode` argument is honored — placing the same blob as executable records
+/// mode 100755, producing a different tree than the regular-mode placement.
+#[test]
+fn write_child_hash_honors_executable_mode() {
+    let sb = Sandbox::new();
+    let blob = sb.repo.write_blob(b"#!/bin/sh\n").unwrap().detach();
+
+    let mut regular = MutableTree::empty();
+    regular
+        .write_child_hash(&sb.repo, "run", blob, 0o100644)
+        .unwrap();
+    let regular_hash = regular.write(&sb.repo).unwrap();
+
+    let mut exec = MutableTree::empty();
+    exec.write_child_hash(&sb.repo, "run", blob, 0o100755)
+        .unwrap();
+    let exec_hash = exec.write(&sb.repo).unwrap();
+
+    assert_ne!(
+        regular_hash, exec_hash,
+        "executable mode must be reflected in the tree entry",
+    );
+}
+
+/// A hash that isn't in the ODB is rejected — no invalid entry is grafted.
+#[test]
+fn write_child_hash_rejects_missing_object() {
+    let sb = Sandbox::new();
+    // A valid-shaped sha1 that was never written to this repo's ODB.
+    let absent: gix::ObjectId = "0123456789abcdef0123456789abcdef01234567"
+        .parse()
+        .unwrap();
+
+    let mut tree = MutableTree::empty();
+    let err = tree
+        .write_child_hash(&sb.repo, "x", absent, 0o100644)
+        .unwrap_err();
+    assert!(matches!(err, holo_tree::Error::Git(_)), "got {err:?}");
+}
+
+/// A hash pointing at a non-blob object (here a tree) is rejected rather than
+/// silently producing a tree entry that claims a blob mode over a tree object.
+#[test]
+fn write_child_hash_rejects_non_blob() {
+    let sb = Sandbox::new();
+    let tree_oid = sb.write_tree(&[("inner.toml", "id = 1\n")]);
+
+    let mut tree = MutableTree::empty();
+    let err = tree
+        .write_child_hash(&sb.repo, "x", tree_oid, 0o100644)
+        .unwrap_err();
+    match err {
+        holo_tree::Error::Git(msg) => assert!(
+            msg.contains("not a blob"),
+            "expected a not-a-blob error, got: {msg}",
+        ),
+        other => panic!("expected Git error, got {other:?}"),
+    }
+}
+
+/// An invalid (non-blob) mode is rejected up front, before any tree mutation —
+/// it would otherwise panic later in `write()` when mapped to an `EntryMode`.
+#[test]
+fn write_child_hash_rejects_invalid_mode() {
+    let sb = Sandbox::new();
+    let blob = sb.repo.write_blob(b"x\n").unwrap().detach();
+
+    let mut tree = MutableTree::empty();
+    // 040000 is a tree mode, not valid for a blob entry.
+    let err = tree
+        .write_child_hash(&sb.repo, "x", blob, 0o040000)
+        .unwrap_err();
+    assert!(matches!(err, holo_tree::Error::Git(_)), "got {err:?}");
+    // The tree must be untouched by a rejected call.
+    assert_eq!(
+        tree.write(&sb.repo).unwrap(),
+        MutableTree::empty().write(&sb.repo).unwrap(),
+        "a rejected write_child_hash must not mutate the tree",
+    );
+}

package/holo-tree-napi/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "holo-tree-napi"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+description = "Node.js native binding for holo-tree — mutable in-memory git trees via gix"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+# Node-API floor of 6 covers Node.js >= 20 comfortably.
+napi = { version = "2", default-features = false, features = ["napi6"] }
+napi-derive = "2"
+holo-tree = { path = "../holo-tree" }
+# gix defaults only — the binding does no networking, so we avoid the TLS/
+# OpenSSL pull-in of `blocking-network-client` to keep cross-compilation clean.
+gix = { version = "0.83" }
+
+[build-dependencies]
+napi-build = "2"

package/holo-tree-napi/README.md

@@ -0,0 +1,144 @@
+# holo-tree-napi
+
+Node.js native binding for [`holo-tree`](../holo-tree) — mutable in-memory git
+trees via [gitoxide](https://github.com/GitoxideLabs/gitoxide), with no `git`
+subprocess.
+
+This crate exposes the narrow slice of holo-tree that record-oriented consumers
+(notably [gitsheets](https://github.com/JarvusInnovations/gitsheets)) need for an
+upsert→commit path. It is intentionally a thin pass-through; it is also the first
+integrated consumer of the new Rust libs, so it doubles as a hardening vehicle —
+rough edges in holo-tree's API are recorded as `Phase-C finding` notes in the
+source and fixed upstream rather than worked around here.
+
+## API
+
+```js
+const { Repo, emptyTreeHash } = require('@hologit/holo-tree');
+
+const repo = Repo.open('/path/to/repo/.git');
+
+const tree = repo.createTreeFromRef('HEAD'); // or repo.createTree() for empty
+tree.writeChild('data/widgets/1.toml', 'id = 1\n'); // hash blob + deep insert
+const treeHash = tree.write(); // flush dirty subtrees → ODB, returns tree hash
+
+const commit = repo.commitTree(treeHash, [parentHash], 'add widget 1');
+repo.updateRef('refs/heads/main', commit);
+
+const bytes = repo.createTreeFromRef(commit).readBlob('data/widgets/1.toml');
+```
+
+Conventions: object ids cross the boundary as lowercase 40-char hex strings;
+blob content crosses as `Buffer` (binary-safe).
+
+### Surface
+
+| Method | holo-tree call | Notes |
+|---|---|---|
+| `Repo.open(gitDir)` | `gix::open().into_sync()` | factory |
+| `repo.createTreeFromRef(ref)` → `Tree` | `repo::create_tree_from_ref` | resolves ref→commit→tree |
+| `repo.createTree()` → `Tree` | `MutableTree::empty` | |
+| `repo.commitTree(treeHash, parents[], msg)` → hash | `repo::commit_tree` | uses git-config identity |
+| `repo.updateRef(ref, hash, expectedOldHash?)` | `repo::update_ref` | compare-and-swap when `expectedOldHash` given; force otherwise |
+| `repo.resolveRef(ref)` → `hash\|null` | `repo::resolve_ref` | peels tags; `null` if unresolved |
+| `repo.writeBlob(buf)` → hash | `gix write_blob` | hash bytes into the ODB, no tree |
+| `tree.writeChild(path, text)` → hash | `MutableTree::write_child` | UTF-8 text |
+| `tree.writeChildBytes(path, buf)` → hash | `MutableTree::write_child_bytes` | binary |
+| `tree.readBlob(path)` → `Buffer\|null` | `MutableTree::read_blob` | |
+| `tree.getChild(path)` → `{type,hash,mode}\|null` | `MutableTree::get_child` | read-only; deep path |
+| `tree.getChildren(path)` → `[{name,type,hash,mode}]` | `get_subtree`+`ensure_children` | read-only; direct children |
+| `tree.getBlobMap(path?)` → `[{path,hash,mode}]` | `get_subtree`+`get_blob_map` | read-only; paths relative to subtree |
+| `tree.deleteChildDeep(path)` → bool | `MutableTree::delete_child_deep` | |
+| `tree.clearChildren(path)` | `MutableTree::clear_children` | O(1) subtree wipe |
+| `tree.merge(other, {files?, mode})` | `MutableTree::merge` | `mode`: `overlay`/`replace`/`underlay` |
+| `tree.write()` → treeHash | `MutableTree::write` | |
+| `emptyTreeHash()` → hash | `tree::empty_tree_id` | module fn |
+
+`mode` values are the git filemode as a number (e.g. `33188` = `0o100644`). Tree
+hashes reported by the read-only navigators reflect the last `write()`/load and
+are stale for a subtree mutated since — flush with `write()` for canonical
+hashes.
+
+## Building
+
+Requires a Rust toolchain and `@napi-rs/cli` (a devDependency):
+
+```sh
+npm install
+npm run build:debug   # or: npm run build   (release)
+npm test              # node --test against a scratch git repo
+```
+
+`napi build` emits `holo-tree.<triple>.node`. The generated `index.js` loader
+and `index.d.ts` types **are committed**; only the `.node` binaries are
+git-ignored (built per-platform in CI).
+
+## Publishing
+
+Published as the scoped package **`@hologit/holo-tree`** with per-platform
+prebuilt binaries shipped as `optionalDependencies`:
+
+| Platform package | Triple | Built on | Smoke-tested |
+| --- | --- | --- | --- |
+| `@hologit/holo-tree-linux-x64-gnu` | `x86_64-unknown-linux-gnu` | ubuntu-latest | ✓ native |
+| `@hologit/holo-tree-linux-arm64-gnu` | `aarch64-unknown-linux-gnu` | ubuntu-24.04-arm | ✓ native |
+| `@hologit/holo-tree-linux-x64-musl` | `x86_64-unknown-linux-musl` | ubuntu-latest (musl cross) | build-only |
+| `@hologit/holo-tree-darwin-arm64` | `aarch64-apple-darwin` | macos-latest | ✓ native |
+| `@hologit/holo-tree-darwin-x64` | `x86_64-apple-darwin` | macos-latest (cross) | build-only |
+| `@hologit/holo-tree-win32-x64-msvc` | `x86_64-pc-windows-msvc` | windows-latest | ✓ native |
+
+Native targets build + smoke-test on a matching runner; cross targets (musl,
+darwin-x64) build only, since their `.node` can't run on the host arch/libc (the
+logic is covered by the native runs). The `.github/workflows/holo-tree-napi.yml`
+workflow builds all six on every PR touching the binding, and on a
+`holo-tree-v*` tag it builds then publishes.
+
+Auth is **npm trusted publishing (OIDC)** — no tokens, matching hologit's
+`publish-npm.yml`. Trusted publishing is configured *per package*, and a package
+can't get a trusted publisher until it exists — so the four packages need a
+**one-time manual bootstrap** before automated releases work.
+
+### One-time bootstrap (manual first publish, then configure trusted publishing)
+
+The four packages all start at an early version (currently `0.0.1`). They must
+exist on npm before trusted publishing can be turned on.
+
+1. **Get the prebuilt binaries.** Run the `holo-tree-napi` workflow (push the
+   branch / open a PR, or trigger `workflow_dispatch`) and download its three
+   `bindings-*` artifacts — they hold the `.node` for each platform. A single
+   machine can't build all three natively, so use the CI artifacts.
+
+2. **Publish all four manually**, logged in as an `@hologit` org member
+   (`npm login`):
+
+   ```sh
+   cd holo-tree-napi
+   npm install
+   npx napi artifacts --dir <downloaded-artifacts-dir>   # → npm/<triple>/*.node
+   # platform packages first, then the main package:
+   for d in npm/*/ ; do ( cd "$d" && npm publish --access public ); done
+   npm publish --access public --ignore-scripts          # main; skip the napi
+                                                         # prepublish hook
+   ```
+
+3. **Turn on trusted publishing** on npmjs.com for **each** of the four packages
+   → Settings → Trusted Publisher → GitHub Actions, repo
+   `JarvusInnovations/hologit`, workflow `holo-tree-napi.yml`.
+
+### Releases (after bootstrap — fully automated, tokenless)
+
+```sh
+git tag holo-tree-v0.1.1 && git push origin holo-tree-v0.1.1
+```
+
+The tag drives the published version; CI builds all three platforms, then
+publishes via OIDC (provenance). No secret needed. The `holo-tree-v*` tag is the
+release marker — napi runs with `--skip-gh-release` so it does **not** create a
+bare `v<version>` GitHub release/tag (which would collide with hologit's own
+`v*` JS-package release namespace).
+
+To add or drop a platform later, edit `napi.triples.additional` +
+`optionalDependencies` in `package.json`, run `napi create-npm-dir -t .`, add the
+matching matrix entry in the workflow, and (since it's a new package) bootstrap
+
++ trust that one package too.

package/holo-tree-napi/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}

package/holo-tree-napi/index.d.ts

@@ -0,0 +1,170 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Git's well-known empty-tree hash (`4b825dc6…`). */
+export declare function emptyTreeHash(): string
+/**
+ * A commit identity (author or committer). `timeSeconds`/`offsetMinutes` are
+ * optional; when omitted the current wall-clock time at UTC is used. Pass them
+ * explicitly to reproduce a specific commit (e.g. match `git commit-tree`
+ * under pinned `GIT_AUTHOR_DATE`/`GIT_COMMITTER_DATE`).
+ */
+export interface Signature {
+  name: string
+  email: string
+  timeSeconds?: number
+  offsetMinutes?: number
+}
+/**
+ * A child entry returned by read-only navigation. `type` is `"tree"`,
+ * `"blob"`, or `"commit"`; `mode` is the git filemode as a number
+ * (e.g. `33188` = `0o100644`, `16384` = `0o040000` for a tree).
+ */
+export interface ChildInfo {
+  type: string
+  hash: string
+  mode: number
+}
+/** A named child entry, returned by `getChildren`. */
+export interface NamedChildInfo {
+  name: string
+  type: string
+  hash: string
+  mode: number
+}
+/**
+ * A blob entry in a flattened blob map, returned by `getBlobMap`. `path` is
+ * relative to the navigated subtree.
+ */
+export interface BlobEntry {
+  path: string
+  hash: string
+  mode: number
+}
+/**
+ * Options for `Tree.merge`. `mode` is `"overlay"`, `"replace"`, or
+ * `"underlay"`; `files` is an optional list of glob patterns restricting which
+ * paths merge (omit to merge everything).
+ */
+export interface MergeOpts {
+  files?: Array<string>
+  mode: string
+}
+/**
+ * A handle to a git repository, backed by gix.
+ *
+ * Stored as a `ThreadSafeRepository` so the handle is `Send + Sync` and can be
+ * cheaply cloned into each `Tree`; every call derives a thread-local
+ * `gix::Repository` via `to_thread_local()`.
+ */
+export declare class Repo {
+  /**
+   * Open a repository at `gitDir` (a `.git` directory, or any path gix can
+   * discover a repo from).
+   */
+  static open(gitDir: string): Repo
+  /**
+   * Resolve a ref (branch, tag, or commit hash) to its tree and return a
+   * mutable, in-memory view of it.
+   */
+  createTreeFromRef(gitRef: string): Tree
+  /** Create a fresh empty, mutable in-memory tree rooted at this repo. */
+  createTree(): Tree
+  /**
+   * Write a commit object pointing at `treeHash` with `parents`. `author`
+   * and `committer` are optional; each falls back to the repo's configured
+   * identity, then a "holo-tree" default. Returns the new commit hash.
+   */
+  commitTree(treeHash: string, parents: Array<string>, message: string, author?: Signature | undefined | null, committer?: Signature | undefined | null): string
+  /**
+   * Point a ref at an object hash.
+   *
+   * When `expectedOldHash` is provided this is a **compare-and-swap**: the
+   * update only succeeds if the ref currently resolves to exactly that hash,
+   * so a concurrent writer who moved the ref makes the swap fail rather than
+   * silently clobbering their commit. Omit it to force the ref (the prior
+   * unconditional behavior).
+   */
+  updateRef(refname: string, hash: string, expectedOldHash?: string | undefined | null): void
+  /**
+   * Resolve a ref / rev-spec (branch, tag, `HEAD`, hash, …) to its commit
+   * hash, peeling annotated tags. Returns `null` when the ref does not
+   * resolve — the natural "does this ref exist?" probe before a CAS
+   * `updateRef`.
+   */
+  resolveRef(gitRef: string): string | null
+  /**
+   * Hash raw bytes as a loose blob in the ODB and return its hash, without
+   * inserting it into any tree. Binary-safe.
+   */
+  writeBlob(content: Buffer): string
+}
+/**
+ * A mutable, in-memory git tree.
+ *
+ * Holds its own clone of the repo handle so JS callers don't thread a repo
+ * argument through every call.
+ *
+ * Phase-C finding #1: holo-tree's `MutableTree` takes `&gix::Repository` on
+ * nearly every method and keeps a *thread-local* tree cache. We smooth the
+ * first half here (the handle lives on the `Tree`) but NOT the second: each
+ * call does `to_thread_local()`, and whether holo-tree's thread-local cache
+ * stays warm across libuv-dispatched calls is the open ergonomics question to
+ * resolve upstream (e.g. a repo-bound tree handle, or an explicit session/
+ * cache object the consumer owns).
+ */
+export declare class Tree {
+  /**
+   * Hash `content` (UTF-8 text) as a blob and insert it at `path`, creating
+   * intermediate trees as needed. Returns the blob hash.
+   */
+  writeChild(path: string, content: string): string
+  /** Hash raw bytes as a blob and insert at `path`. Binary-safe. */
+  writeChildBytes(path: string, content: Buffer): string
+  /**
+   * Place an already-written blob at `path` by its `hash`, without reading its
+   * bytes. Unlike `writeChildBytes` (which re-hashes content), this grafts a
+   * blob already in the ODB — validated to exist and be a blob via a header
+   * lookup, so a large attachment isn't read back and re-hashed. `mode` is the
+   * git filemode: `0o100644` regular, `0o100755` executable, `0o120000`
+   * symlink. Returns the placed hash.
+   */
+  writeChildHash(path: string, hash: string, mode: number): string
+  /** Read a blob's bytes at `path`, or `null` if no blob exists there. */
+  readBlob(path: string): Buffer | null
+  /**
+   * Read-only: look up the child at a deep `path` and report its type,
+   * hash, and mode, or `null` if nothing exists there.
+   */
+  getChild(path: string): ChildInfo | null
+  /**
+   * Read-only: list the direct children of the subtree at `path` (use `"."`
+   * for the root). Returns an empty array if `path` is missing or not a tree.
+   */
+  getChildren(path: string): Array<NamedChildInfo>
+  /**
+   * Read-only: recursively collect every blob under the subtree at `path`
+   * (defaults to the whole tree) into a flat list. Each `path` is relative
+   * to the navigated subtree. Returns an empty array if `path` is missing.
+   */
+  getBlobMap(path?: string | undefined | null): Array<BlobEntry>
+  /** Delete a child at a deep `path`. Returns whether it existed. */
+  deleteChildDeep(path: string): boolean
+  /**
+   * Clear all children under a deep `path` in O(1) — replace the subtree
+   * there with the empty tree (and dirty its ancestors) without loading the
+   * cleared subtree's contents. `path == "."` clears the whole tree. Used to
+   * wipe a directory before a full rewrite.
+   */
+  clearChildren(path: string): void
+  /**
+   * Merge another tree into this one in place, per `options.mode`
+   * (`overlay`/`replace`/`underlay`) and optional `options.files` globs.
+   * `other` must be a *different* `Tree` instance.
+   */
+  merge(other: Tree, options: MergeOpts): void
+  /** Flush dirty subtrees to the ODB and return the resulting tree hash. */
+  write(): string
+}