hanna/fabrica

feat(git): bare-repo creation and the in-process read API

d52473f · hanna committed on 2026-07-25

Begin phase 5. `crates/git` wraps libgit2 (`git2`) for the in-process object
model — transport stays a spawned-`git` concern for later.

- Layout + creation: repo_path shards by ULID (`{root}/{id[0..2]}/{id}.git`);
  create_bare does init_bare with the initial HEAD, the server config
  (logAllRefUpdates, denyNonFastForwards=false, gc.auto=0), and the
  post-receive/pre-receive hooks, cleaning up the directory on any failure.
- Read API in the plain `types` vocabulary (no `git2` in public signatures, so
  `web` never links libgit2 semantics): resolve_ref, tree_entries, blob (with
  binary sniff), branches (ahead/behind vs default), tags (annotated vs
  lightweight), commits (newest-first, optional path filter, paged), commit.
- Oids are hex strings, times epoch-ms; methods are blocking and documented to
  require spawn_blocking off the async runtime.

Integration tests build a real bare repo via git2 and exercise every read.
git2 is pinned to a libgit2-sys matching nixpkgs' libgit2 1.9.4, and the dev
shell exports LD_LIBRARY_PATH for the dynamic link; both are in decisions.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +57 −1

Cargo.toml +4 −0

crates/git/Cargo.toml +12 −0

crates/git/src/lib.rs +239 −1

crates/git/src/repo.rs +707 −0

crates/git/src/types.rs +218 −0

docs/decisions.md +30 −0

flake.nix +5 −0

 checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
 dependencies = [
  "find-msvc-tools",
+ "jobserver",
+ "libc",
  "shlex",
+]
 [[package]]
 name = "git"
 version = "0.1.0"
+dependencies = [
+ "git2",
+ "libgit2-sys",
+ "model",
+ "tempfile",
+ "thiserror",
+]
+[[package]]
+name = "git2"
+version = "0.20.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b88256088d75a56f8ecfa070513a775dd9107f6530ef14919dac831af9cfe2b"
+dependencies = [
+ "bitflags",
+ "libc",
+ "libgit2-sys",
+ "log",
+ "url",
+]
 [[package]]
 name = "hashbrown"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
+name = "jobserver"
+version = "0.1.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3"
+dependencies = [
+ "getrandom 0.4.3",
+ "libc",
+]
+[[package]]
 name = "js-sys"
 version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 [[package]]
+name = "libgit2-sys"
+version = "0.18.3+1.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9b3acc4b91781bb0b3386669d325163746af5f6e4f73e6d2d630e09a35f3487"
+dependencies = [
+ "cc",
+ "libc",
+ "libz-sys",
+ "pkg-config",
+]
+[[package]]
 name = "libsqlite3-sys"
 version = "0.37.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "libz-sys"
+version = "1.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85bc9657773828b90eeb625adff10eeac83cc21bbfd8e23a03eaa8a33c9e28d9"
+dependencies = [
+ "cc",
+ "libc",
+ "pkg-config",
+ "vcpkg",
+]
+[[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.4.3",
+ "getrandom 0.3.4",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",

 ulid = "1"
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 tempfile = "3"
+# Git object model (refs, trees, blobs, commits, diffs, signatures). Linked
+# against the system libgit2 (1.9) via pkg-config; the Nix build sets
+# LIBGIT2_NO_VENDOR=1. Client-only for transport — pack transport spawns `git`.
+git2 = { version = "0.20", default-features = false }
 # Authentication primitives. Argon2id password hashing; SHA-256 for session and
 # invite token digests; HMAC-SHA256 for hand-rolled HS256 JWTs (avoiding a `ring`
 # dependency, whose license set is not in our allow-list — see docs/decisions.md);

 publish.workspace = true
 [dependencies]
+model = { workspace = true }
+git2 = { workspace = true }
+thiserror = { workspace = true }
+# Pin the libgit2 bindings to a build that requires libgit2 <= the version
+# nixpkgs ships (1.9.4). git2 0.20's default libgit2-sys (0.18.7, bundling 1.9.6)
+# demands >= 1.9.6 and fails against the system lib under LIBGIT2_NO_VENDOR. This
+# is a direct pin, not used in code — bump it when nixpkgs bumps libgit2. See
+# docs/decisions.md.
+libgit2-sys = "=0.18.3"
+[dev-dependencies]
+tempfile = { workspace = true }
 [lints]
 workspace = true

 lands, this path grows the invite-and-email behaviour; the `passwd` fallback stays
 for SMTP-disabled instances (`mail.backend = "none"`), which is exactly the case
 that motivated it.
+## 2026-07-24 — git2 pinned to the libgit2 nixpkgs ships (1.9.4)
+**Decision:** `crates/git` depends on `git2` 0.20 with a direct
+`libgit2-sys = "=0.18.3"` pin, and the build uses the **system** libgit2
+(`LIBGIT2_NO_VENDOR=1`, already set in the flake) rather than the vendored copy.
+**Alternatives:** Let `libgit2-sys` build its bundled libgit2 from source (drop
+`LIBGIT2_NO_VENDOR`, add `cmake`); track `git2`'s latest `libgit2-sys`.
+**Rationale:** `git2` 0.20's default `libgit2-sys` (0.18.7, bundling 1.9.6)
+requires libgit2 ≥ 1.9.6 and aborts against nixpkgs' 1.9.4 under
+`LIBGIT2_NO_VENDOR`. `libgit2-sys` 0.18.3 (bundling 1.9.2) requires ≥ 1.9.2,
+which 1.9.4 satisfies. The exact pin makes the coupling explicit and stops a
+stray `cargo update` from reintroducing the mismatch; bump it in lockstep when
+nixpkgs bumps libgit2. Using the system lib keeps builds fast and avoids a `cmake`
+build-dep and a second copy of libgit2 in the graph.
+## 2026-07-24 — Dev shell sets LD_LIBRARY_PATH for dynamic libgit2
+**Decision:** The `devShells.default` exports
+`LD_LIBRARY_PATH = makeLibraryPath buildInputs`.
+**Alternatives:** Rely on rpath; require developers to set it themselves.
+**Rationale:** Test and bin artifacts built interactively (`cargo test`,
+`cargo run` in the dev shell) link libgit2 dynamically but do not receive the Nix
+build sandbox's rpath, so the loader cannot find `libgit2.so.1.9` and the binary
+exits 127. The Nix build's own checks (`nix flake check`) embed rpath and are
+unaffected; this only fixes the interactive `just check` path.

             ];
             buildInputs = commonArgs.buildInputs;
             LIBGIT2_NO_VENDOR = "1";
+            # Test/bin artifacts built interactively link libgit2 dynamically but
+            # do not get the build sandbox's rpath, so the loader needs the lib
+            # dirs on the search path for `cargo test`/`cargo run` to work in the
+            # shell. (The Nix build embeds rpath itself, so its checks don't.)
+            LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath commonArgs.buildInputs;
           };
           formatter = pkgs.nixpkgs-fmt;

 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-//! The git layer: in-process object reads via libgit2 and spawned pack transport.
+//! The git layer: object-model reads over `git2`, on-disk repository layout, and
+//! (in later phases) attribute resolution, signature verification, and
+//! pack-transport spawning.
+//!
+//! # Division of responsibility
+//!
+//! `git2` (libgit2) is the object-model library — refs, trees, blobs, commits,
+//! revwalks, diffs, signatures. It is **client-only for transport**: there is no
+//! server-side `upload-pack`/`receive-pack`, so clone/fetch/push are handled by
+//! spawning the `git` binary (a later phase). This crate owns the in-process
+//! reads and the bare-repository creation that both paths share.
+//!
+//! # Threading
+//!
+//! libgit2 calls are blocking and `git2::Repository` is not `Sync`. Callers on an
+//! async runtime **MUST** run these methods on `tokio::task::spawn_blocking` (or a
+//! bounded blocking pool); [`Repo`] is opened per operation, which is acceptable
+//! for the MVP. Nothing here spawns threads or touches the network.
+//!
+//! # Layout
+//!
+//! Repositories live at `{repo_dir}/{id[0..2]}/{id}.git` keyed by ULID, never by
+//! name, so renames and group moves are metadata-only. The database is the sole
+//! name→path authority; [`repo_path`] is the one place that mapping is computed.
+mod repo;
+mod types;
+use std::fs;
+use std::io;
+use std::os::unix::fs::PermissionsExt;
+use std::path::{Path, PathBuf};
+use git2::{Repository, RepositoryInitOptions};
+pub use crate::repo::Repo;
+pub use crate::types::{
+    Blob, BranchInfo, CommitDetail, CommitSummary, EntryKind, Oid, Page, Person, RefKind, Resolved,
+    TagInfo, TreeEntry,
+};
+/// An error from the git layer.
+#[derive(Debug, thiserror::Error)]
+pub enum GitError {
+    /// An error surfaced by libgit2.
+    #[error(transparent)]
+    Libgit2(#[from] git2::Error),
+    /// A filesystem operation failed, with the path that was being touched.
+    #[error("git io error at {path}: {source}")]
+    Io {
+        /// The path involved.
+        path: PathBuf,
+        /// The underlying I/O error.
+        source: io::Error,
+    },
+    /// A repository id was too short to shard (ids are 26-char ULIDs).
+    #[error("repository id {0:?} is too short")]
+    BadId(String),
+    /// A revision string did not resolve to any ref or object.
+    #[error("revision {0:?} not found")]
+    RevNotFound(String),
+    /// A path was not present in the given tree.
+    #[error("path {0:?} not found")]
+    PathNotFound(String),
+    /// A path resolved to something other than a file where a file was required.
+    #[error("path {0:?} is not a file")]
+    NotAFile(String),
+}
+/// Compute the on-disk path of a repository from its id: `{root}/{id[0..2]}/{id}.git`.
+///
+/// # Errors
+///
+/// Returns [`GitError::BadId`] if `id` is shorter than the two-character shard
+/// prefix.
+pub fn repo_path(root: &Path, id: &str) -> Result<PathBuf, GitError> {
+    if id.len() < 2 {
+        return Err(GitError::BadId(id.to_string()));
+    }
+    Ok(root.join(&id[0..2]).join(format!("{id}.git")))
+}
+/// Create a bare repository for `id` under `root` and return an open handle.
+///
+/// Performs the filesystem half of repo creation (the caller inserts the database
+/// row): `init_bare` with `HEAD` pointing at `default_branch`; the config the
+/// server relies on (`core.logAllRefUpdates=true`, `receive.denyNonFastForwards=
+/// false`, `gc.auto=0` — maintenance is fabrica-driven, not push-driven); and the
+/// `post-receive`/`pre-receive` hooks that shell out to `hook_binary`.
+///
+/// On any failure after the directory is created, the partially built directory
+/// is removed so a retry starts clean.
+///
+/// # Errors
+///
+/// Returns [`GitError`] if the id is invalid, the directory already exists, or any
+/// libgit2/filesystem step fails.
+pub fn create_bare(
+    root: &Path,
+    id: &str,
+    default_branch: &str,
+    hook_binary: &Path,
+) -> Result<Repo, GitError> {
+    let path = repo_path(root, id)?;
+    if path.exists() {
+        return Err(GitError::Io {
+            path: path.clone(),
+            source: io::Error::new(io::ErrorKind::AlreadyExists, "repository directory exists"),
+        });
+    }
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|source| GitError::Io {
+            path: parent.to_path_buf(),
+            source,
+        })?;
+    }
+    // Any error past this point should not leave a half-built repo behind.
+    match init_inner(&path, default_branch, hook_binary) {
+        Ok(()) => Repo::open_path(&path),
+        Err(err) => {
+            let _ = fs::remove_dir_all(&path);
+            Err(err)
+        }
+    }
+}
+/// The fallible body of [`create_bare`], separated so the caller can clean up on
+/// any error.
+fn init_inner(path: &Path, default_branch: &str, hook_binary: &Path) -> Result<(), GitError> {
+    let mut opts = RepositoryInitOptions::new();
+    opts.bare(true).initial_head(default_branch).mkpath(true);
+    let repo = Repository::init_opts(path, &opts)?;
+    let mut config = repo.config()?;
+    config.set_bool("core.logallrefupdates", true)?;
+    config.set_bool("receive.denyNonFastForwards", false)?;
+    config.set_i32("gc.auto", 0)?;
+    install_hooks(path, hook_binary)?;
+    Ok(())
+}
+/// Write the `post-receive` and `pre-receive` hooks. `post-receive` dispatches to
+/// `fabrica hook post-receive`; `pre-receive` is a reserved no-op. Both are made
+/// executable.
+fn install_hooks(repo_path: &Path, hook_binary: &Path) -> Result<(), GitError> {
+    let hooks_dir = repo_path.join("hooks");
+    fs::create_dir_all(&hooks_dir).map_err(|source| GitError::Io {
+        path: hooks_dir.clone(),
+        source,
+    })?;
+    let binary = hook_binary.display();
+    write_hook(
+        &hooks_dir.join("post-receive"),
+        &format!("#!/bin/sh\nexec \"{binary}\" hook post-receive\n"),
+    )?;
+    // Reserved for future branch protection; accepts every push for now.
+    write_hook(&hooks_dir.join("pre-receive"), "#!/bin/sh\nexit 0\n")?;
+    Ok(())
+}
+/// Write a single hook file and mark it executable (`0o755`).
+fn write_hook(path: &Path, contents: &str) -> Result<(), GitError> {
+    fs::write(path, contents).map_err(|source| GitError::Io {
+        path: path.to_path_buf(),
+        source,
+    })?;
+    fs::set_permissions(path, fs::Permissions::from_mode(0o755)).map_err(|source| {
+        GitError::Io {
+            path: path.to_path_buf(),
+            source,
+        }
+    })?;
+    Ok(())
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    #[test]
+    fn repo_path_shards_by_id_prefix() {
+        let root = Path::new("/srv/repos");
+        let path = repo_path(root, "01hzxk9m2n8p7q6r5s4t3v2w1x").unwrap();
+        assert_eq!(
+            path,
+            Path::new("/srv/repos/01/01hzxk9m2n8p7q6r5s4t3v2w1x.git")
+        );
+    }
+    #[test]
+    fn repo_path_rejects_short_ids() {
+        assert!(matches!(
+            repo_path(Path::new("/srv"), "a"),
+            Err(GitError::BadId(_))
+        ));
+    }
+    #[test]
+    fn create_bare_sets_head_config_and_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let repo = create_bare(
+            dir.path(),
+            "01hzxk9m2n8p7q6r5s4t3v2w1x",
+            "trunk",
+            Path::new("/usr/bin/fabrica"),
+        )
+        .unwrap();
+        // HEAD points at the requested initial branch.
+        assert_eq!(repo.head_branch().unwrap().as_deref(), Some("trunk"));
+        let path = repo_path(dir.path(), "01hzxk9m2n8p7q6r5s4t3v2w1x").unwrap();
+        // The hook exists, is executable, and dispatches to `fabrica hook`.
+        let hook = path.join("hooks").join("post-receive");
+        let body = std::fs::read_to_string(&hook).unwrap();
+        assert!(body.contains("hook post-receive"), "body: {body}");
+        let mode = std::fs::metadata(&hook).unwrap().permissions().mode();
+        assert_eq!(mode & 0o111, 0o111, "hook must be executable");
+    }
+    #[test]
+    fn create_bare_is_not_clobbering() {
+        let dir = tempfile::tempdir().unwrap();
+        let id = "01hzxk9m2n8p7q6r5s4t3v2w1x";
+        create_bare(dir.path(), id, "main", Path::new("/usr/bin/fabrica")).unwrap();
+        // A second create at the same id fails (the directory already exists).
+        assert!(create_bare(dir.path(), id, "main", Path::new("/usr/bin/fabrica")).is_err());
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! An open repository and its read operations.
+//!
+//! Every method here is synchronous and blocking; see the crate docs for the
+//! `spawn_blocking` requirement. The public surface speaks only in the plain
+//! [`crate::types`] vocabulary — `git2` handles never escape this module.
+use std::path::Path;
+use git2::{BranchType, Commit, Repository, Signature, Sort, TreeEntry as GitTreeEntry};
+use crate::GitError;
+use crate::types::{
+    Blob, BranchInfo, CommitDetail, CommitSummary, EntryKind, Oid, Page, Person, RefKind, Resolved,
+    TagInfo, TreeEntry,
+};
+/// Filemode bits git uses to distinguish tree-entry kinds.
+const MODE_DIR: i32 = 0o040_000;
+const MODE_SYMLINK: i32 = 0o120_000;
+const MODE_SUBMODULE: i32 = 0o160_000;
+/// Bytes sniffed from the head of a blob when deciding whether it is binary.
+const BINARY_SNIFF_BYTES: usize = 8_000;
+/// An open bare repository.
+pub struct Repo {
+    inner: Repository,
+}
+impl Repo {
+    /// Open the repository at `path` (expected to be a bare `.git` directory).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::Libgit2`] if the path is not a repository.
+    pub fn open_path(path: &Path) -> Result<Self, GitError> {
+        Ok(Self {
+            inner: Repository::open_bare(path)?,
+        })
+    }
+    /// The branch name `HEAD` points at, even when that branch is unborn (a
+    /// freshly created repo with no commits). Returns `None` if `HEAD` is
+    /// detached.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::Libgit2`] if `HEAD` cannot be read.
+    pub fn head_branch(&self) -> Result<Option<String>, GitError> {
+        let head = self.inner.find_reference("HEAD")?;
+        Ok(head
+            .symbolic_target()
+            .and_then(|t| t.strip_prefix("refs/heads/"))
+            .map(str::to_string))
+    }
+    /// Resolve a revision string — a branch or tag name, `HEAD`, or a raw commit
+    /// id — to the commit it names.
+    ///
+    /// Resolution order is branch, then tag, then a general parse (which covers
+    /// `HEAD`, full and abbreviated oids, and revspecs). A branch and a tag of the
+    /// same name resolve to the branch, matching git's own precedence for a bare
+    /// short name in this context.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::RevNotFound`] if nothing matches.
+    pub fn resolve_ref(&self, rev: &str) -> Result<Resolved, GitError> {
+        if let Ok(branch) = self.inner.find_branch(rev, BranchType::Local) {
+            let commit = branch.get().peel_to_commit()?;
+            return Ok(Resolved {
+                oid: oid_of(commit.id()),
+                kind: RefKind::Branch,
+                name: rev.to_string(),
+            });
+        }
+        if let Ok(reference) = self.inner.find_reference(&format!("refs/tags/{rev}")) {
+            let commit = reference.peel_to_commit()?;
+            return Ok(Resolved {
+                oid: oid_of(commit.id()),
+                kind: RefKind::Tag,
+                name: rev.to_string(),
+            });
+        }
+        let object = self
+            .inner
+            .revparse_single(rev)
+            .map_err(|_| GitError::RevNotFound(rev.to_string()))?;
+        let commit = object
+            .peel_to_commit()
+            .map_err(|_| GitError::RevNotFound(rev.to_string()))?;
+        Ok(Resolved {
+            oid: oid_of(commit.id()),
+            kind: if rev == "HEAD" {
+                RefKind::Head
+            } else {
+                RefKind::Commit
+            },
+            name: rev.to_string(),
+        })
+    }
+    /// List the entries of the tree at `path` within revision `rev`. An empty
+    /// `path` lists the root tree. Directories sort before files, each
+    /// alphabetically.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::PathNotFound`] if `path` is absent or names a file.
+    pub fn tree_entries(&self, rev: &Resolved, path: &Path) -> Result<Vec<TreeEntry>, GitError> {
+        let commit = self.commit_at(&rev.oid)?;
+        let root = commit.tree()?;
+        let tree = if path.components().next().is_none() {
+            root
+        } else {
+            let entry = root
+                .get_path(path)
+                .map_err(|_| GitError::PathNotFound(path.display().to_string()))?;
+            entry
+                .to_object(&self.inner)?
+                .into_tree()
+                .map_err(|_| GitError::PathNotFound(path.display().to_string()))?
+        };
+        let mut entries: Vec<TreeEntry> = tree
+            .iter()
+            .map(|entry| self.map_tree_entry(&entry))
+            .collect();
+        entries.sort_by(|a, b| {
+            let a_dir = a.kind == EntryKind::Directory;
+            let b_dir = b.kind == EntryKind::Directory;
+            b_dir.cmp(&a_dir).then_with(|| a.name.cmp(&b.name))
+        });
+        Ok(entries)
+    }
+    /// Read the file at `path` within revision `rev`.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::PathNotFound`] if `path` is absent, or
+    /// [`GitError::NotAFile`] if it names a directory or submodule.
+    pub fn blob(&self, rev: &Resolved, path: &Path) -> Result<Blob, GitError> {
+        let commit = self.commit_at(&rev.oid)?;
+        let entry = commit
+            .tree()?
+            .get_path(path)
+            .map_err(|_| GitError::PathNotFound(path.display().to_string()))?;
+        let object = entry.to_object(&self.inner)?;
+        let blob = object
+            .into_blob()
+            .map_err(|_| GitError::NotAFile(path.display().to_string()))?;
+        let content = blob.content().to_vec();
+        let size = content.len() as u64;
+        Ok(Blob {
+            is_binary: looks_binary(&content),
+            size,
+            content,
+        })
+    }
+    /// The local branches, each with its position (ahead/behind) relative to the
+    /// default branch and its tip commit.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::Libgit2`] on a libgit2 failure.
+    pub fn branches(&self) -> Result<Vec<BranchInfo>, GitError> {
+        let default = self.head_branch()?;
+        let default_oid = default
+            .as_deref()
+            .and_then(|name| self.inner.find_branch(name, BranchType::Local).ok())
+            .and_then(|branch| branch.get().peel_to_commit().ok())
+            .map(|commit| commit.id());
+        let mut out = Vec::new();
+        for branch in self.inner.branches(Some(BranchType::Local))? {
+            let (branch, _) = branch?;
+            let Some(name) = branch.name()?.map(str::to_string) else {
+                continue;
+            };
+            let tip = branch.get().peel_to_commit()?;
+            let (ahead, behind) = match default_oid {
+                Some(base) if base != tip.id() => self.inner.graph_ahead_behind(tip.id(), base)?,
+                _ => (0, 0),
+            };
+            out.push(BranchInfo {
+                is_default: default.as_deref() == Some(name.as_str()),
+                name,
+                oid: oid_of(tip.id()),
+                ahead,
+                behind,
+                tip: commit_summary(&tip),
+            });
+        }
+        out.sort_by(|a, b| {
+            b.is_default
+                .cmp(&a.is_default)
+                .then_with(|| a.name.cmp(&b.name))
+        });
+        Ok(out)
+    }
+    /// The tags, peeled to the commit each ultimately points at, annotated tags
+    /// carrying their message and tagger.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::Libgit2`] on a libgit2 failure.
+    pub fn tags(&self) -> Result<Vec<TagInfo>, GitError> {
+        let mut out = Vec::new();
+        for name in self.inner.tag_names(None)?.iter().flatten() {
+            let object = self.inner.revparse_single(&format!("refs/tags/{name}"))?;
+            let commit = object.peel_to_commit()?;
+            let (annotated, message, tagger) = match object.as_tag() {
+                Some(tag) => (
+                    true,
+                    tag.message().map(str::to_string),
+                    tag.tagger().as_ref().map(person),
+                ),
+                None => (false, None, None),
+            };
+            out.push(TagInfo {
+                name: name.to_string(),
+                oid: oid_of(commit.id()),
+                annotated,
+                message,
+                tagger,
+            });
+        }
+        out.sort_by(|a, b| a.name.cmp(&b.name));
+        Ok(out)
+    }
+    /// Walk commits reachable from `rev`, newest first, returning one page.
+    ///
+    /// When `path` is given, only commits that changed that path are returned
+    /// (compared against the first parent — a pragmatic history simplification,
+    /// not full merge-aware path following). Paging is applied *after* filtering.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::Libgit2`] on a libgit2 failure.
+    pub fn commits(
+        &self,
+        rev: &Resolved,
+        path: Option<&Path>,
+        page: Page,
+    ) -> Result<Vec<CommitSummary>, GitError> {
+        let start = git2::Oid::from_str(rev.oid.as_str())?;
+        let mut walk = self.inner.revwalk()?;
+        walk.set_sorting(Sort::TIME)?;
+        walk.push(start)?;
+        let mut out = Vec::with_capacity(page.limit);
+        let mut skipped = 0usize;
+        for oid in walk {
+            let commit = self.inner.find_commit(oid?)?;
+            if let Some(path) = path {
+                if !commit_touches(&commit, path)? {
+                    continue;
+                }
+            }
+            if skipped < page.offset {
+                skipped += 1;
+                continue;
+            }
+            out.push(commit_summary(&commit));
+            if out.len() >= page.limit {
+                break;
+            }
+        }
+        Ok(out)
+    }
+    /// Fetch a single commit in full.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::RevNotFound`] if no such commit exists.
+    pub fn commit(&self, oid: &Oid) -> Result<CommitDetail, GitError> {
+        let commit = self.commit_at(oid)?;
+        Ok(CommitDetail {
+            oid: oid_of(commit.id()),
+            message: commit.message().unwrap_or("").to_string(),
+            author: person(&commit.author()),
+            committer: person(&commit.committer()),
+            parents: commit.parent_ids().map(oid_of).collect(),
+            tree: oid_of(commit.tree_id()),
+        })
+    }
+    /// Look up a commit by our [`Oid`], mapping a miss to [`GitError::RevNotFound`].
+    fn commit_at(&self, oid: &Oid) -> Result<Commit<'_>, GitError> {
+        let parsed = git2::Oid::from_str(oid.as_str())
+            .map_err(|_| GitError::RevNotFound(oid.to_string()))?;
+        self.inner
+            .find_commit(parsed)
+            .map_err(|_| GitError::RevNotFound(oid.to_string()))
+    }
+    /// Map a libgit2 tree entry into our [`TreeEntry`], reading blob sizes for
+    /// files and symlinks.
+    fn map_tree_entry(&self, entry: &GitTreeEntry<'_>) -> TreeEntry {
+        let mode = entry.filemode();
+        let kind = match mode {
+            MODE_DIR => EntryKind::Directory,
+            MODE_SUBMODULE => EntryKind::Submodule,
+            MODE_SYMLINK => EntryKind::Symlink,
+            _ => EntryKind::File,
+        };
+        let size = match kind {
+            EntryKind::File | EntryKind::Symlink => self
+                .inner
+                .find_blob(entry.id())
+                .ok()
+                .map(|b| b.size() as u64),
+            EntryKind::Directory | EntryKind::Submodule => None,
+        };
+        TreeEntry {
+            name: entry.name().unwrap_or_default().to_string(),
+            kind,
+            // Filemodes are small positive octal constants; the fallback is
+            // unreachable for a well-formed tree entry.
+            mode: u32::try_from(mode).unwrap_or(0),
+            oid: oid_of(entry.id()),
+            size,
+        }
+    }
+}
+/// Whether `commit` changed `path` relative to its first parent (or, for a root
+/// commit, whether the path exists in it).
+fn commit_touches(commit: &Commit<'_>, path: &Path) -> Result<bool, GitError> {
+    let here = entry_oid(commit, path)?;
+    match commit.parent(0) {
+        Ok(parent) => Ok(here != entry_oid(&parent, path)?),
+        // No parent: the commit touches the path iff the path exists in it.
+        Err(_) => Ok(here.is_some()),
+    }
+}
+/// The object id at `path` in a commit's tree, or `None` if the path is absent.
+fn entry_oid(commit: &Commit<'_>, path: &Path) -> Result<Option<git2::Oid>, GitError> {
+    let tree = commit.tree()?;
+    Ok(tree.get_path(path).ok().map(|entry| entry.id()))
+}
+/// Convert a libgit2 oid to our hex [`Oid`].
+fn oid_of(oid: git2::Oid) -> Oid {
+    Oid::new(oid.to_string())
+}
+/// Build a [`Person`] from a libgit2 signature, converting the second-resolution
+/// time to epoch milliseconds.
+fn person(sig: &Signature<'_>) -> Person {
+    Person {
+        name: sig.name().unwrap_or_default().to_string(),
+        email: sig.email().unwrap_or_default().to_string(),
+        time_ms: sig.when().seconds().saturating_mul(1000),
+    }
+}
+/// Build a [`CommitSummary`] for a log row.
+fn commit_summary(commit: &Commit<'_>) -> CommitSummary {
+    CommitSummary {
+        oid: oid_of(commit.id()),
+        summary: commit.summary().unwrap_or("").to_string(),
+        author: person(&commit.author()),
+        parents: commit.parent_count(),
+    }
+}
+/// Heuristic binary sniff: a NUL byte in the head of the content marks it binary,
+/// matching git's own `core.check-blob-content` behaviour closely enough for a
+/// "don't try to render this" decision.
+fn looks_binary(bytes: &[u8]) -> bool {
+    let window = &bytes[..bytes.len().min(BINARY_SNIFF_BYTES)];
+    window.contains(&0)
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used)]
+    use std::path::{Path, PathBuf};
+    use git2::{Repository, Signature, Time};
+    use tempfile::TempDir;
+    use super::*;
+    use crate::{create_bare, repo_path};
+    const ID: &str = "01hzxk9m2n8p7q6r5s4t3v2w1x";
+    /// A populated bare repository plus the temp dir keeping it alive.
+    struct Fixture {
+        _dir: TempDir,
+        path: PathBuf,
+        /// Oids of the commits made, in creation order.
+        commits: Vec<git2::Oid>,
+    }
+    /// Build a bare repo with:
+    /// - `main`: commit1 (README + src/main.rs), commit2 (README changed only);
+    /// - `feature`: commit3 on top of commit2 (adds src/extra.rs);
+    /// - an annotated tag `v1.0` on commit1 and a lightweight tag `light` on commit2.
+    fn fixture() -> Fixture {
+        let dir = tempfile::tempdir().unwrap();
+        create_bare(dir.path(), ID, "main", Path::new("/usr/bin/fabrica")).unwrap();
+        let path = repo_path(dir.path(), ID).unwrap();
+        let raw = Repository::open_bare(&path).unwrap();
+        let c1 = commit(
+            &raw,
+            "main",
+            &[],
+            &[("README.md", "hello\n"), ("src/main.rs", "fn main() {}\n")],
+            "initial import",
+,
+        );
+        let c2 = commit(
+            &raw,
+            "main",
+            &[c1],
+            &[
+                ("README.md", "hello world\n"),
+                ("src/main.rs", "fn main() {}\n"),
+            ],
+            "expand readme",
+,
+        );
+        let c3 = commit(
+            &raw,
+            "feature",
+            &[c2],
+            &[
+                ("README.md", "hello world\n"),
+                ("src/main.rs", "fn main() {}\n"),
+                ("src/extra.rs", "// extra\n"),
+            ],
+            "add extra module",
+,
+        );
+        // Tags: annotated on c1, lightweight on c2.
+        let obj = raw.find_object(c1, None).unwrap();
+        let tagger = Signature::new("Ada", "ada@example.com", &Time::new(10_000, 0)).unwrap();
+        raw.tag("v1.0", &obj, &tagger, "the first release", false)
+            .unwrap();
+        raw.reference("refs/tags/light", c2, true, "lightweight")
+            .unwrap();
+        Fixture {
+            _dir: dir,
+            path,
+            commits: vec![c1, c2, c3],
+        }
+    }
+    /// Write `files` (paths may contain one level of nesting) as a tree and commit
+    /// it onto `branch`, returning the new commit oid. `t` seeds the commit time so
+    /// ordering is deterministic.
+    fn commit(
+        raw: &Repository,
+        branch: &str,
+        parents: &[git2::Oid],
+        files: &[(&str, &str)],
+        message: &str,
+        t: i64,
+    ) -> git2::Oid {
+        use std::collections::BTreeMap;
+        // Group files by their (single) directory prefix.
+        let mut by_dir: BTreeMap<Option<String>, Vec<(String, git2::Oid)>> = BTreeMap::new();
+        for (path, content) in files {
+            let blob = raw.blob(content.as_bytes()).unwrap();
+            let (dir, name) = match path.split_once('/') {
+                Some((dir, name)) => (Some(dir.to_string()), name.to_string()),
+                None => (None, (*path).to_string()),
+            };
+            by_dir.entry(dir).or_default().push((name, blob));
+        }
+        let mut root = raw.treebuilder(None).unwrap();
+        for (dir, entries) in by_dir {
+            match dir {
+                None => {
+                    for (name, blob) in entries {
+                        root.insert(&name, blob, 0o100_644).unwrap();
+                    }
+                }
+                Some(dir) => {
+                    let mut sub = raw.treebuilder(None).unwrap();
+                    for (name, blob) in entries {
+                        sub.insert(&name, blob, 0o100_644).unwrap();
+                    }
+                    let sub_oid = sub.write().unwrap();
+                    root.insert(&dir, sub_oid, 0o040_000).unwrap();
+                }
+            }
+        }
+        let tree_oid = root.write().unwrap();
+        let tree = raw.find_tree(tree_oid).unwrap();
+        let sig = Signature::new("Ada Lovelace", "ada@example.com", &Time::new(t, 0)).unwrap();
+        let parent_commits: Vec<_> = parents
+            .iter()
+            .map(|p| raw.find_commit(*p).unwrap())
+            .collect();
+        let parent_refs: Vec<&git2::Commit> = parent_commits.iter().collect();
+        raw.commit(
+            Some(&format!("refs/heads/{branch}")),
+            &sig,
+            &sig,
+            message,
+            &tree,
+            &parent_refs,
+        )
+        .unwrap()
+    }
+    fn open(fx: &Fixture) -> Repo {
+        Repo::open_path(&fx.path).unwrap()
+    }
+    #[test]
+    fn resolve_ref_covers_branch_tag_head_oid_and_miss() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let c2 = fx.commits[1].to_string();
+        let main = repo.resolve_ref("main").unwrap();
+        assert_eq!(main.kind, RefKind::Branch);
+        assert_eq!(main.oid.as_str(), c2);
+        let head = repo.resolve_ref("HEAD").unwrap();
+        assert_eq!(head.kind, RefKind::Head);
+        assert_eq!(head.oid.as_str(), c2, "HEAD tracks the default branch");
+        let tag = repo.resolve_ref("v1.0").unwrap();
+        assert_eq!(tag.kind, RefKind::Tag);
+        assert_eq!(tag.oid.as_str(), fx.commits[0].to_string());
+        let raw = repo.resolve_ref(&c2).unwrap();
+        assert_eq!(raw.kind, RefKind::Commit);
+        assert_eq!(raw.oid.as_str(), c2);
+        assert!(matches!(
+            repo.resolve_ref("nope"),
+            Err(GitError::RevNotFound(_))
+        ));
+    }
+    #[test]
+    fn tree_entries_lists_root_and_subdir_dirs_first() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let main = repo.resolve_ref("main").unwrap();
+        let root = repo.tree_entries(&main, Path::new("")).unwrap();
+        let names: Vec<_> = root.iter().map(|e| e.name.as_str()).collect();
+        assert_eq!(names, ["src", "README.md"], "directories sort first");
+        assert_eq!(root[0].kind, EntryKind::Directory);
+        assert_eq!(root[1].kind, EntryKind::File);
+        assert_eq!(root[1].size, Some("hello world\n".len() as u64));
+        let src = repo.tree_entries(&main, Path::new("src")).unwrap();
+        assert_eq!(
+            src.iter().map(|e| e.name.as_str()).collect::<Vec<_>>(),
+            ["main.rs"]
+        );
+        assert!(matches!(
+            repo.tree_entries(&main, Path::new("does/not/exist")),
+            Err(GitError::PathNotFound(_))
+        ));
+        // A file path is not a directory.
+        assert!(matches!(
+            repo.tree_entries(&main, Path::new("README.md")),
+            Err(GitError::PathNotFound(_))
+        ));
+    }
+    #[test]
+    fn blob_reads_content_and_flags() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let main = repo.resolve_ref("main").unwrap();
+        let readme = repo.blob(&main, Path::new("README.md")).unwrap();
+        assert_eq!(readme.content, b"hello world\n");
+        assert_eq!(readme.size, 12);
+        assert!(!readme.is_binary);
+        // A directory is not a file.
+        assert!(matches!(
+            repo.blob(&main, Path::new("src")),
+            Err(GitError::NotAFile(_))
+        ));
+        assert!(matches!(
+            repo.blob(&main, Path::new("missing")),
+            Err(GitError::PathNotFound(_))
+        ));
+    }
+    #[test]
+    fn branches_report_default_and_ahead_behind() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let branches = repo.branches().unwrap();
+        let names: Vec<_> = branches.iter().map(|b| b.name.as_str()).collect();
+        assert_eq!(names, ["main", "feature"], "default sorts first");
+        let main = &branches[0];
+        assert!(main.is_default);
+        assert_eq!((main.ahead, main.behind), (0, 0));
+        let feature = &branches[1];
+        assert!(!feature.is_default);
+        // feature is one commit ahead of main and behind by none.
+        assert_eq!((feature.ahead, feature.behind), (1, 0));
+        assert_eq!(feature.tip.summary, "add extra module");
+    }
+    #[test]
+    fn tags_distinguish_annotated_from_lightweight() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let tags = repo.tags().unwrap();
+        let names: Vec<_> = tags.iter().map(|t| t.name.as_str()).collect();
+        assert_eq!(names, ["light", "v1.0"]);
+        let light = tags.iter().find(|t| t.name == "light").unwrap();
+        assert!(!light.annotated);
+        assert_eq!(light.oid.as_str(), fx.commits[1].to_string());
+        assert!(light.message.is_none());
+        let v1 = tags.iter().find(|t| t.name == "v1.0").unwrap();
+        assert!(v1.annotated);
+        assert_eq!(v1.oid.as_str(), fx.commits[0].to_string());
+        assert_eq!(v1.message.as_deref(), Some("the first release"));
+        assert_eq!(v1.tagger.as_ref().unwrap().name, "Ada");
+    }
+    #[test]
+    fn commits_walk_newest_first_and_filter_by_path() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let main = repo.resolve_ref("main").unwrap();
+        let all = repo.commits(&main, None, Page::first(10)).unwrap();
+        let summaries: Vec<_> = all.iter().map(|c| c.summary.as_str()).collect();
+        assert_eq!(summaries, ["expand readme", "initial import"]);
+        // Paging: skip the newest, take one.
+        let page = repo
+            .commits(
+                &main,
+                None,
+                Page {
+                    offset: 1,
+                    limit: 1,
+                },
+            )
+            .unwrap();
+        assert_eq!(page.len(), 1);
+        assert_eq!(page[0].summary, "initial import");
+        // src/main.rs was only introduced in commit1 and unchanged since.
+        let touched = repo
+            .commits(&main, Some(Path::new("src/main.rs")), Page::first(10))
+            .unwrap();
+        assert_eq!(
+            touched
+                .iter()
+                .map(|c| c.summary.as_str())
+                .collect::<Vec<_>>(),
+            ["initial import"]
+        );
+    }
+    #[test]
+    fn commit_returns_full_detail() {
+        let fx = fixture();
+        let repo = open(&fx);
+        let c2 = Oid::new(fx.commits[1].to_string());
+        let detail = repo.commit(&c2).unwrap();
+        assert_eq!(detail.message, "expand readme");
+        assert_eq!(detail.author.name, "Ada Lovelace");
+        assert_eq!(detail.author.email, "ada@example.com");
+        assert_eq!(detail.parents, vec![Oid::new(fx.commits[0].to_string())]);
+        assert!(matches!(
+            repo.commit(&Oid::new("0".repeat(40))),
+            Err(GitError::RevNotFound(_))
+        ));
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! The public vocabulary of the git layer.
+//!
+//! None of these types expose `git2`: the object ids are plain hex strings, times
+//! are epoch-millisecond integers, and the shapes carry exactly what the `web`
+//! and `api` crates render — so those crates never link against libgit2 semantics
+//! and the read API stays swappable.
+/// A git object id, stored as its lowercase 40-char hex string.
+///
+/// A newtype rather than a bare `String` so it cannot be confused with a ref
+/// name or a path, and so the `git2` conversion stays inside this crate.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Oid(String);
+impl Oid {
+    /// Wrap a hex string as an [`Oid`]. The value is lowercased; no validation is
+    /// performed here — resolution against a repository is where an unknown id is
+    /// rejected.
+    #[must_use]
+    pub fn new(hex: impl Into<String>) -> Self {
+        Self(hex.into().to_lowercase())
+    }
+    /// The hex string.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+    /// The conventional 7-character short form for display.
+    #[must_use]
+    pub fn short(&self) -> &str {
+        let end = self.0.len().min(7);
+        &self.0[..end]
+    }
+}
+impl std::fmt::Display for Oid {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+/// What a ref string resolved to.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RefKind {
+    /// A branch (`refs/heads/…`).
+    Branch,
+    /// A tag (`refs/tags/…`), annotated or lightweight.
+    Tag,
+    /// A raw commit id, given directly rather than through a ref.
+    Commit,
+    /// The repository `HEAD`.
+    Head,
+}
+/// A resolved revision: the commit it points at, how it was named, and the name
+/// itself (a branch/tag name, or the oid string for a raw commit).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Resolved {
+    /// The commit the revision resolves to.
+    pub oid: Oid,
+    /// How the revision was named.
+    pub kind: RefKind,
+    /// The human name: branch or tag name, `HEAD`, or the oid for a raw commit.
+    pub name: String,
+}
+/// The kind of a tree entry.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EntryKind {
+    /// A subdirectory (another tree).
+    Directory,
+    /// A regular or executable file (a blob).
+    File,
+    /// A symbolic link (a blob whose content is the link target).
+    Symlink,
+    /// A submodule (a gitlink commit id).
+    Submodule,
+}
+/// One entry in a tree listing.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TreeEntry {
+    /// The entry's name (the final path segment).
+    pub name: String,
+    /// Its kind.
+    pub kind: EntryKind,
+    /// The unix file mode (e.g. `0o100644`).
+    pub mode: u32,
+    /// The object id the entry points at.
+    pub oid: Oid,
+    /// The blob size in bytes, for files; `None` for directories and submodules.
+    pub size: Option<u64>,
+}
+/// A blob's bytes plus the facts a view needs before deciding how to render it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Blob {
+    /// The raw content.
+    pub content: Vec<u8>,
+    /// Its size in bytes (`content.len()`, surfaced for convenience).
+    pub size: u64,
+    /// Whether the content looks binary (contains a NUL in the sniff window).
+    pub is_binary: bool,
+}
+/// A person and the moment they acted, as recorded on a commit or tag.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Person {
+    /// Display name.
+    pub name: String,
+    /// Email address.
+    pub email: String,
+    /// The action time, epoch milliseconds UTC.
+    pub time_ms: i64,
+}
+/// A commit as shown in a log list — enough for one row.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CommitSummary {
+    /// The commit id.
+    pub oid: Oid,
+    /// The first line of the message.
+    pub summary: String,
+    /// Who wrote the change.
+    pub author: Person,
+    /// Number of parents (0 for a root commit, ≥2 for a merge).
+    pub parents: usize,
+}
+/// A commit in full, for the commit page.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CommitDetail {
+    /// The commit id.
+    pub oid: Oid,
+    /// The complete message.
+    pub message: String,
+    /// Who wrote the change.
+    pub author: Person,
+    /// Who committed it (may differ from the author).
+    pub committer: Person,
+    /// The parent commit ids.
+    pub parents: Vec<Oid>,
+    /// The root tree id.
+    pub tree: Oid,
+}
+/// A branch and its position relative to the default branch.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BranchInfo {
+    /// The branch name (without the `refs/heads/` prefix).
+    pub name: String,
+    /// The commit it points at.
+    pub oid: Oid,
+    /// Whether this is the repository's default branch.
+    pub is_default: bool,
+    /// Commits ahead of the default branch (0 for the default branch itself).
+    pub ahead: usize,
+    /// Commits behind the default branch.
+    pub behind: usize,
+    /// The tip commit, for the "last updated" column.
+    pub tip: CommitSummary,
+}
+/// A tag and what it points at.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TagInfo {
+    /// The tag name (without the `refs/tags/` prefix).
+    pub name: String,
+    /// The commit the tag ultimately points at (peeled).
+    pub oid: Oid,
+    /// Whether the tag is annotated (has its own object) vs. lightweight.
+    pub annotated: bool,
+    /// The annotation message, for annotated tags.
+    pub message: Option<String>,
+    /// The tagger, for annotated tags.
+    pub tagger: Option<Person>,
+}
+/// A half-open slice of a listing: skip `offset`, take `limit`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Page {
+    /// How many items to skip from the start.
+    pub offset: usize,
+    /// How many items to return.
+    pub limit: usize,
+}
+impl Page {
+    /// The first page of `limit` items.
+    #[must_use]
+    pub fn first(limit: usize) -> Self {
+        Self { offset: 0, limit }
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn oid_lowercases_and_shortens() {
+        let oid = Oid::new("ABCDEF1234567890ABCDEF1234567890ABCDEF12");
+        assert_eq!(oid.as_str(), "abcdef1234567890abcdef1234567890abcdef12");
+        assert_eq!(oid.short(), "abcdef1");
+        assert_eq!(oid.to_string(), oid.as_str());
+    }
+    #[test]
+    fn short_handles_undersized_ids() {
+        assert_eq!(Oid::new("abc").short(), "abc");
+    }
+}