@scolladon/tsgit 1.0.0 → 1.2.0

package/dist/types/primitives/index.d.cts

@@ -1,217 +1,439 @@
-import { O as ObjectId, d as FilePath, b as Context, R as RefName } from '../chunks/context-d36639-i.cjs';
-import { A as AuthorIdentity, F as FileMode, T as TreeDiff } from '../chunks/diff-change-B09vxnxy.cjs';
-import '../chunks/http-transport-DirKfK2S.cjs';
+import { G as GitIndex, I as IndexEntry } from '../chunks/write-tree-B8G6kgTy.cjs';
+export { H as HookInput, c as catFileBatch, a as createCommit, d as diffTrees, g as getRepoRoot, m as mergeBase, r as readBlob, b as readIndex, e as readObject, f as readTree, h as recordRefUpdate, i as resolveRef, j as runHook, s as sparseCheckoutPath, u as updateRef, w as walkCommits, k as walkSubmodules, l as walkTree, n as walkWorkingTree, o as writeObject, p as writeSymbolicRef, q as writeTree } from '../chunks/write-tree-B8G6kgTy.cjs';
+import { d as FilePath, O as ObjectId, b as Context, R as RefName } from '../chunks/context-CMrHCVwK.cjs';
+import { F as FileMode, A as AuthorIdentity, q as ReflogEntry } from '../chunks/reflog-entry-BIf-zt__.cjs';
+export { C as CatFileBatchEntry, a as CatFileBatchOptions, c as CreateCommitInput, D as DiffTreesInput, d as DiffTreesOptions, M as MAX_COMMIT_MESSAGE_BYTES, e as MAX_GITIGNORE_BYTES, f as MAX_GITMODULES_BYTES, g as MAX_HAVES, h as MAX_INDEX_BYTES, i as MAX_PEEL_DEPTH, j as MAX_PUSH_OBJECTS, k as MAX_REFLOG_BYTES, l as MAX_SUBMODULE_DEPTH, m as MAX_SYMBOLIC_REF_DEPTH, n as MAX_WALK_QUEUE_SIZE, o as MAX_WALK_SEEDS, p as MAX_WORKING_TREE_BLOB_BYTES, R as ReadObjectOptions, r as ResolveRefOptions, S as SubmoduleEntry, s as TreeDiff, U as UpdateRefOptions, W as WalkCommitsOptions, u as WalkIgnorePredicate, v as WalkSubmodulesOptions, w as WalkTreeEntry, x as WalkTreeOptions, y as WalkWorkingTreeEntry, z as WalkWorkingTreeOptions } from '../chunks/reflog-entry-BIf-zt__.cjs';
+import { b as HttpTransport } from '../chunks/http-transport-DirKfK2S.cjs';
 
-interface Blob {
-    readonly type: 'blob';
-    readonly id: ObjectId;
-    readonly content: Uint8Array;
-}
+/** `true` ⇒ the path is in the sparse set (materialise it). */
+type SparseMatcher = (path: FilePath) => boolean;
 
-interface ExtraHeader {
-    readonly key: string;
-    readonly value: string;
+/**
+ * Pure helper that diffs a current GitIndex against a target tree's flat
+ * entry list and emits an ordered ChangesetEntry list. No FS, no ctx; the
+ * impure write side lives in `apply-changeset.ts`.
+ *
+ * Stage-0 entries only — unmerged stages are invisible to checkout (Phase
+ * 13.1 design step 5).
+ */
+
+interface ChangesetEntry {
+    readonly kind: 'add' | 'update' | 'delete' | 'noop';
+    readonly path: FilePath;
+    readonly mode: FileMode;
+    readonly id: ObjectId | undefined;
+    readonly previousId: ObjectId | undefined;
+    readonly previousMode: FileMode | undefined;
 }
-interface CommitData {
-    readonly tree: ObjectId;
-    readonly parents: ReadonlyArray<ObjectId>;
-    readonly author: AuthorIdentity;
-    readonly committer: AuthorIdentity;
-    readonly message: string;
-    readonly gpgSignature?: string;
-    readonly extraHeaders: ReadonlyArray<ExtraHeader>;
-}
-interface Commit {
-    readonly type: 'commit';
-    readonly id: ObjectId;
-    readonly data: CommitData;
+interface ChangesetStats {
+    readonly add: number;
+    readonly update: number;
+    readonly delete: number;
+    readonly noop: number;
 }
-
-type ObjectType = 'blob' | 'tree' | 'commit' | 'tag';
-
-interface TagData {
-    readonly object: ObjectId;
-    readonly objectType: ObjectType;
-    readonly tagName: string;
-    readonly tagger?: AuthorIdentity;
-    readonly message: string;
-    readonly gpgSignature?: string;
-    readonly extraHeaders: ReadonlyArray<ExtraHeader>;
+interface Changeset {
+    readonly entries: ReadonlyArray<ChangesetEntry>;
+    readonly stats: ChangesetStats;
 }
-interface Tag {
-    readonly type: 'tag';
+interface TargetEntry {
+    readonly path: FilePath;
     readonly id: ObjectId;
-    readonly data: TagData;
+    readonly mode: FileMode;
 }
+declare const computeChangeset: (currentIndex: GitIndex, targetTree: ReadonlyArray<TargetEntry>) => Changeset;
 
-interface TreeEntry {
-    readonly mode: FileMode;
-    readonly name: string;
-    readonly id: ObjectId;
+interface ApplyChangesetOpts {
+    readonly changeset: Changeset;
+    readonly force: boolean;
+    readonly workdir: string;
 }
-interface Tree {
-    readonly type: 'tree';
-    readonly id: ObjectId;
-    readonly entries: ReadonlyArray<TreeEntry>;
+interface ApplyChangesetResult {
+    readonly writtenEntries: ReadonlyArray<IndexEntry>;
+    readonly written: number;
+    readonly deleted: number;
 }
+/**
+ * `true` when a working-tree file exists at `absPath` but its blob content
+ * hash differs from `expectedId`. An absent file is not dirty. Shared by
+ * `applySparseCheckout`'s narrowing pre-scan (design §9).
+ */
+declare const isWorkingTreeDirty: (ctx: Context, absPath: string, expectedId: string) => Promise<boolean>;
+declare const applyChangeset: (ctx: Context, opts: ApplyChangesetOpts) => Promise<ApplyChangesetResult>;
 
-type GitObject = Blob | Tree | Commit | Tag;
+/**
+ * Project a target tree onto a fresh stage-0 IndexEntry list, preserving
+ * stat-cache fields from the prior index where the path's `id` AND `mode`
+ * both match (the "stat-cache donor" strategy).
+ *
+ * Pure with respect to the working tree: this primitive never calls
+ * `fs.lstat`, `fs.read`, or any working-tree-side API. It only reads git
+ * objects via `walkTree` → `readObject` for nested trees.
+ *
+ * Used by `reset --mixed` to rebuild the index from a target
+ * commit's tree. Will be re-used by `reset --hard` composed
+ * with `materializeTree` to also write the working tree.
+ *
+ * ## Preconditions
+ *
+ * `currentIndex` MUST be read under the same `acquireIndexLock` that will
+ * later commit the result. Reading the index BEFORE the lock is acquired
+ * lets a concurrent writer mutate it between the donor-map build and the
+ * commit, producing a result that reflects neither the pre-reset nor the
+ * post-reset state. See `reset.ts:rebuildIndexFromCommit` for the
+ * canonical pattern: acquire → read → build → commit → release-in-finally.
+ */
 
-interface IndexEntryFlags {
-    readonly assumeValid: boolean;
-    readonly extended: boolean;
-    readonly stage: 0 | 1 | 2 | 3;
+interface BuildIndexFromTreeOpts {
+    readonly targetTree: ObjectId;
+    readonly currentIndex: GitIndex;
+    /**
+     * Sparse-checkout filter. When supplied, an excluded path is rebuilt as a
+     * zero-stat skip-worktree entry and an in-pattern path has any stale
+     * skip-worktree bit cleared. `undefined` ⇒ sparse inactive — the rebuilt
+     * index is byte-identical to the non-sparse behaviour.
+     */
+    readonly sparse?: SparseMatcher;
 }
-interface IndexEntry {
-    readonly ctimeSeconds: number;
-    readonly ctimeNanoseconds: number;
-    readonly mtimeSeconds: number;
-    readonly mtimeNanoseconds: number;
-    readonly dev: number;
-    readonly ino: number;
-    readonly mode: FileMode;
-    readonly uid: number;
-    readonly gid: number;
-    readonly fileSize: number;
-    readonly id: ObjectId;
-    readonly flags: IndexEntryFlags;
-    readonly path: FilePath;
+declare const buildIndexFromTree: (ctx: Context, opts: BuildIndexFromTreeOpts) => Promise<ReadonlyArray<IndexEntry>>;
+
+interface BuildPackInput {
+    readonly oids: ReadonlyArray<ObjectId>;
 }
-interface IndexExtension {
-    readonly signature: string;
-    readonly data: Uint8Array;
+interface BuildPackResult {
+    readonly bytes: Uint8Array;
+    /** Hex SHA of the pack body, also the trailer (last 20 bytes). */
+    readonly sha: string;
+    readonly objectCount: number;
 }
-interface GitIndex {
-    readonly version: 2;
-    readonly entries: ReadonlyArray<IndexEntry>;
-    readonly extensions: ReadonlyArray<IndexExtension>;
+declare const buildPack: (ctx: Context, input: BuildPackInput) => Promise<BuildPackResult>;
+
+/**
+ * Subset of `.git/config` that v1 commands consume. Only fields actually used by
+ * commands are typed — the parser ignores everything else (lenient, like git itself).
+ */
+interface ParsedConfig {
+    readonly core?: {
+        readonly bare?: boolean;
+        readonly excludesFile?: string;
+        readonly logAllRefUpdates?: boolean | 'always';
+        readonly hooksPath?: string;
+        readonly sparseCheckout?: boolean;
+        readonly sparseCheckoutCone?: boolean;
+    };
+    readonly user?: {
+        readonly name: string;
+        readonly email: string;
+    };
+    readonly remote?: ReadonlyMap<string, {
+        readonly url?: string;
+        readonly fetch?: ReadonlyArray<string>;
+        /** `remote.<name>.promisor` — true when this is a partial-clone promisor remote. */
+        readonly promisor?: boolean;
+        /** `remote.<name>.partialclonefilter` — the canonical filter spec applied at clone. */
+        readonly partialCloneFilter?: string;
+    }>;
+    readonly branch?: ReadonlyMap<string, {
+        readonly remote?: string;
+        readonly merge?: string;
+    }>;
+    /** `[extensions]` — `partialClone` names the promisor remote of a partial clone. */
+    readonly extensions?: {
+        readonly partialClone?: string;
+    };
 }
+/**
+ * Read and cache `${gitDir}/config`. Missing → empty config (not an error).
+ *
+ * The cache is keyed on `Context` identity; a new context (e.g., after a write
+ * that re-creates the repo) gets a fresh read. Concurrent calls share the same
+ * in-flight promise (per-context single-flight).
+ */
+declare const readConfig: (ctx: Context) => Promise<ParsedConfig>;
+/**
+ * Drop the cached `readConfig` entry for a single `Context`. The production
+ * invalidator: a config write (`updateCoreConfig`) calls this so a subsequent
+ * `readConfig` on the same context re-reads the file instead of serving the
+ * stale parse.
+ */
+declare const invalidateConfigCache: (ctx: Context) => void;
 
-interface RenameDetectOptions {
-    readonly limit?: number;
-    readonly maxSameIdDeletes?: number;
+interface EnumeratePushObjectsInput {
+    /**
+     * Object ids the caller wants on the remote. Each MUST resolve to a
+     * commit or an annotated tag (tags are unwrapped to commits before the
+     * commit walk).
+     */
+    readonly wants: ReadonlyArray<ObjectId>;
+    /** Object ids the remote already has (server's advertised ref tips). */
+    readonly haves: ReadonlyArray<ObjectId>;
+    /** Hard cap on objects emitted. Defaults to MAX_PUSH_OBJECTS. */
+    readonly maxObjects?: number;
 }
+declare function enumeratePushObjects(ctx: Context, input: EnumeratePushObjectsInput): AsyncIterable<ObjectId>;
 
 /**
- * Phase 7 primitive option shapes, walker value types, and shared constants.
- * Defined in one location to avoid circular imports between primitive modules.
+ * Enumerate every current ref: `HEAD`, loose refs under `.git/refs/**`, and
+ * packed-refs entries — deduplicated. Used by `reflog expire` to seed the
+ * reachable-commit walk; not on any hot path.
  */
 
-/** Max symbolic-ref dereferences resolveRef will follow. */
-declare const MAX_SYMBOLIC_REF_DEPTH = 5;
-/** Max tag-peel hops resolveRef / readTree will follow when peeling. */
-declare const MAX_PEEL_DEPTH = 5;
-/** Max seeds walkCommits.from can contain. */
-declare const MAX_WALK_SEEDS = 1024;
-/** Hard cap on walkCommits' pending queue size to prevent unbounded heap growth. */
-declare const MAX_WALK_QUEUE_SIZE: number;
-/** Max .git/index file size readIndex will accept. */
-declare const MAX_INDEX_BYTES: number;
-/** Max commit message byte length createCommit will accept. */
-declare const MAX_COMMIT_MESSAGE_BYTES: number;
-interface ReadObjectOptions {
-    readonly verifyHash?: boolean;
-}
-interface ResolveRefOptions {
-    readonly peel?: boolean;
-    readonly maxSymbolicDepth?: number;
-    readonly maxPeelDepth?: number;
-}
-interface UpdateRefOptions {
-    readonly expected?: ObjectId | 'absent';
-    readonly delete?: boolean;
-}
-interface WalkCommitsOptions {
-    readonly from: ReadonlyArray<ObjectId>;
-    readonly until?: ReadonlyArray<ObjectId>;
-    readonly order?: 'topo' | 'first-parent';
-    readonly ignoreMissing?: boolean;
-    readonly verifyHash?: boolean;
-}
-interface WalkTreeEntry {
-    readonly path: FilePath;
-    readonly id: ObjectId;
-    readonly mode: FileMode;
-}
-interface WalkTreeOptions {
-    readonly recursive?: boolean;
-    readonly maxDepth?: number;
-    readonly maxEntries?: number;
-}
-interface CreateCommitInput {
-    readonly tree: ObjectId;
-    readonly parents: ReadonlyArray<ObjectId>;
-    readonly author: AuthorIdentity;
-    readonly committer: AuthorIdentity;
-    readonly message: string;
-    readonly gpgSignature?: string;
-    readonly extraHeaders?: ReadonlyArray<ExtraHeader>;
+declare function enumerateRefs(ctx: Context): Promise<ReadonlyArray<RefName>>;
+
+interface FetchPackInput {
+    /** Advertised refs the caller wants. MUST be non-empty (server-side requirement). */
+    readonly wants: ReadonlyArray<ObjectId>;
+    /** Objects the caller already has (negotiation). Empty for clone, populated for fetch. */
+    readonly haves: ReadonlyArray<ObjectId>;
+    /** Negotiated capabilities (intersection of advertised + supported). */
+    readonly capabilities: ReadonlyArray<string>;
+    /** Base remote URL (the same URL passed to clone). */
+    readonly url: string;
+    /** Progress op label — clone uses 'clone:write-objects', fetch uses 'fetch:write-objects'. */
+    readonly progressOp: string;
+    /**
+     * Shallow clone depth. When set, sends `deepen N` and consumes the
+     * accompanying `shallow <oid>` / `unshallow <oid>` response block.
+     *
+     */
+    readonly depth?: number;
+    /**
+     * Partial-clone object filter — a canonical filter spec. When set, a
+     * `filter` line is emitted; the caller must have negotiated the `filter`
+     * capability.
+     */
+    readonly filter?: string;
+    /**
+     * When true, write an empty `pack-<sha>.promisor` sentinel beside the pack
+     * so the objects it references but omits are treated as promised.
+     */
+    readonly promisor?: boolean;
 }
-type DiffTreesInput = Tree | ObjectId | undefined;
-interface DiffTreesOptions {
-    readonly detectRenames?: boolean;
-    readonly renameOptions?: RenameDetectOptions;
+interface FetchPackResult {
+    readonly packPath: string;
+    readonly idxPath: string;
+    readonly objectCount: number;
+    /** Hex-encoded SHA of the pack trailer; also the on-disk filename stem. */
+    readonly packSha: string;
+    /** Commits the server advertised as new shallow boundaries (empty when depth is unset). */
+    readonly shallow: ReadonlyArray<ObjectId>;
+    /** Commits the server advertised as no-longer-shallow (empty when depth is unset). */
+    readonly unshallow: ReadonlyArray<ObjectId>;
 }
-
-declare function createCommit(ctx: Context, input: CreateCommitInput): Promise<ObjectId>;
-
-declare function diffTrees(ctx: Context, a: DiffTreesInput, b: DiffTreesInput, options?: DiffTreesOptions): Promise<TreeDiff>;
+declare const fetchPack: (ctx: Context, transport: HttpTransport, input: FetchPackInput) => Promise<FetchPackResult>;
 
 /**
- * Compute a merge base — the first commit reachable from BOTH `a` and `b`.
+ * Compose `walkTree → computeChangeset → applyChangeset` to update the
+ * working tree to a target tree's contents.
+ *
+ * - Branch switch mode: `paths === undefined` — diff the entire current
+ *  index against the entire target tree.
+ * - Path-restore mode: `paths !== undefined` — restrict both sides of
+ *  the diff to those paths.
  *
- * Algorithm: bidirectional BFS with two visited sets. After each layer
- * advance, check the intersection. When non-empty, return the
- * lexicographically smallest oid (deterministic tie-breaker).
+ * Returns the new IndexEntry list for the caller to commit, plus
+ * written/deleted counts. The primitive does NOT commit the index — the
+ * caller decides.
  *
- * Returns `undefined` for unrelated histories. Documented limitation: cherry-picks
- * and criss-cross merges may yield non-optimal bases — `recursive`-strategy
- * multi-base resolution is v2.
+ * ## Stat-source contract for `newIndexEntries` (load-bearing for)
+ *
+ * - **Paths that were written/added** (`add` or `update` changeset entries):
+ *  the IndexEntry carries **post-write `lstat`-derived stat fields**
+ *  (ctime/mtime/dev/ino/uid/gid/fileSize). These reflect the file we just
+ *  wrote, so the next `status` runs the fast `isStatClean` path.
+ * - **Paths whose changeset classification was `noop`** (skipped — index
+ *  already matched target by `id + mode`): the IndexEntry is the caller's
+ *  `currentIndex` entry verbatim. Donor stats survive across the call.
+ * - `reset --hard` therefore MUST set `forceRewriteAll: true` so every noop
+ *  upgrades to update and the post-write stats land in the output. Without
+ *  that, a locally-modified working-tree file that the index still records
+ *  as clean would survive the reset, AND the donor stats would be stale
+ *  relative to the actual disk state.
  */
-declare const mergeBase: (ctx: Context, a: ObjectId, b: ObjectId) => Promise<ObjectId | undefined>;
+
+interface MaterializeTreeOpts {
+    readonly targetTree: ObjectId;
+    readonly currentIndex: GitIndex;
+    readonly force?: boolean;
+    readonly paths?: ReadonlySet<FilePath>;
+    /**
+     * When true, every target-tree path is written to the working tree
+     * unconditionally — even paths the index→target diff classified as `noop`
+     * (same `id` AND `mode`). Required by `reset --hard`, where the working
+     * tree may diverge from the index (uncommitted local modifications); the
+     * standard index→target diff cannot see that drift, so noops would skip
+     * paths the caller wants overwritten. Default `false` keeps the Phase
+     * 13.1 checkout behaviour: clean files are never spuriously rewritten.
+     */
+    readonly forceRewriteAll?: boolean;
+    /**
+     * Branch-switch sparse-checkout filter. Honoured ONLY when `paths` is
+     * undefined. A target-tree path the matcher rejects is NOT written to the
+     * working tree; its `newIndexEntries` record carries `skipWorktree: true`
+     * (the index keeps every path — git-faithful). A path the matcher accepts
+     * that the *current* index records as skip-worktree (absent on disk) is
+     * materialised even when its `id` matches, because the current index is
+     * filtered to drop skip-worktree entries before the diff — such a path
+     * classifies as `add`, never `noop`.
+     */
+    readonly sparse?: SparseMatcher;
+}
+interface MaterializeTreeResult {
+    readonly newIndexEntries: ReadonlyArray<IndexEntry>;
+    readonly written: number;
+    readonly deleted: number;
+}
+declare const materializeTree: (ctx: Context, opts: MaterializeTreeOpts) => Promise<MaterializeTreeResult>;
 
 /**
- * Pure path helpers composing `ctx.layout.gitDir` with known sub-paths.
- * No I/O. No port access. Primitive step 3.
+ * Hard cap on the `.git/info/sparse-checkout` file — 1 MiB, mirroring
+ * `MAX_GITIGNORE_BYTES`. A plain literal (not `1024 * 1024`) so a boundary test
+ * keyed on the constant cannot drift with an arithmetic mutation of it.
  */
-
+declare const MAX_SPARSE_PATTERN_FILE_BYTES = 1048576;
 /**
- * Repository working-tree root. Returns the workDir from the current context;
- * facade-tier code (Phase 10) is responsible for discovery / realpath pinning
- * at construction time. Primitives consume the already-resolved path.
+ * Read `.git/info/sparse-checkout` as UTF-8 text. An absent file yields
+ * `undefined`; a file whose byte length exceeds
+ * `MAX_SPARSE_PATTERN_FILE_BYTES` throws `SPARSE_PATTERN_FILE_TOO_LARGE`
+ * (checked before decode so an over-cap file never reaches the decoder).
  */
-declare const getRepoRoot: (ctx: Context) => FilePath;
-
-declare function readBlob(ctx: Context, id: ObjectId, options?: ReadObjectOptions): Promise<Blob>;
-
-declare function readIndex(ctx: Context): Promise<GitIndex>;
-
-declare function readObject(ctx: Context, id: ObjectId, options?: ReadObjectOptions): Promise<GitObject>;
+declare const readSparsePatternText: (ctx: Context) => Promise<string | undefined>;
+/**
+ * Build the sparse matcher for the current repository. Returns `undefined`
+ * when `core.sparseCheckout` is falsy/absent — sparse is inactive and callers
+ * behave exactly as a non-sparse repo. When active, the matcher is parsed in
+ * the mode `core.sparseCheckoutCone` dictates; a cone file that degrades to
+ * non-cone matching logs one warning.
+ */
+declare const loadSparseMatcher: (ctx: Context) => Promise<SparseMatcher | undefined>;
 
-declare function readTree(ctx: Context, ref: RefName | ObjectId): Promise<Tree>;
+/**
+ * Committer identity for reflog entries: config `user.*` plus a fresh
+ * timestamp, or a portable fallback when `user.*` is unset. Never throws —
+ * reflog logging must not abort a ref update.
+ */
+declare function resolveReflogIdentity(ctx: Context): Promise<AuthorIdentity>;
 
-declare function resolveRef(ctx: Context, name: RefName | 'HEAD', options?: ResolveRefOptions): Promise<ObjectId>;
+/**
+ * Thin I/O layer over `.git/logs/<ref>` reflog files. Append is the hot path;
+ * whole-file rewrite and delete back the `reflog` command's expire / delete.
+ */
 
-declare function updateRef(ctx: Context, name: RefName, newId: ObjectId, options?: UpdateRefOptions): Promise<void>;
+/** Append one entry to `ref`'s reflog, creating the file and parents as needed. */
+declare function appendReflog(ctx: Context, ref: RefName, entry: ReflogEntry): Promise<void>;
+/** Read `ref`'s reflog, oldest-first. Returns `[]` when the file is absent. */
+declare function readReflog(ctx: Context, ref: RefName): Promise<ReadonlyArray<ReflogEntry>>;
+/** Whether `ref` has a reflog file at all. */
+declare function reflogExists(ctx: Context, ref: RefName): Promise<boolean>;
+/** Replace `ref`'s reflog with exactly `entries`. Used by expire / delete. */
+declare function writeReflog(ctx: Context, ref: RefName, entries: ReadonlyArray<ReflogEntry>): Promise<void>;
+/** Remove `ref`'s reflog file. A no-op when the file is already absent. */
+declare function deleteReflog(ctx: Context, ref: RefName): Promise<void>;
+/** Every reflog under `.git/logs/`, each as the `RefName` it logs. */
+declare function listReflogs(ctx: Context): Promise<ReadonlyArray<RefName>>;
 
-declare function walkCommits(ctx: Context, options: WalkCommitsOptions): AsyncIterable<Commit>;
+/**
+ * Read `.git/shallow`. Returns an empty set when the file does not exist or
+ * contains no oids. Malformed lines are tolerated (skipped) — canonical
+ * git behaves the same; a corrupted shallow file should not block a fetch.
+ */
+declare const readShallow: (ctx: Context) => Promise<ReadonlySet<ObjectId>>;
+interface ShallowUpdate {
+    readonly shallow: ReadonlyArray<ObjectId>;
+    readonly unshallow: ReadonlyArray<ObjectId>;
+}
+/**
+ * Apply a set of shallow / unshallow updates to `.git/shallow`. Writes
+ * atomically via lock-rename; deletes the file when the resulting set is
+ * empty.
+ */
+declare const updateShallow: (ctx: Context, updates: ShallowUpdate) => Promise<void>;
 
-declare function walkTree(ctx: Context, treeIdOrObject: ObjectId | Tree, options?: WalkTreeOptions): AsyncIterable<WalkTreeEntry>;
+/**
+ * Synthesise a nested `Tree` object from a flat `GitIndex` and return the
+ * root tree's `ObjectId`. Sub-trees are written to the object store as a
+ * side-effect of the recursive descent — only stage-0 entries contribute.
+ *
+ * Used by `checkout({ paths, source: 'index' })` to restore
+ * the working tree from staged content even when the index has diverged
+ * from HEAD via `add` / `rm`. The previous placeholder fell back to
+ * HEAD's tree, which silently lost the divergence.
+ *
+ * The synthesis is the inverse of `buildIndexFromTree`:
+ * "tree → index" and "index → tree" form a round-trip identity for any
+ * stage-0-only index.
+ *
+ * Pure with respect to the working tree — never calls `fs.lstat`,
+ * `fs.read`, or any working-tree-side API. Only writes git objects via
+ * the existing `writeTree` primitive.
+ *
+ * ## Safety
+ *
+ * - **Path validation**:.7 hoisted segment-level validation into
+ *  `parseIndex` (`src/domain/git-index/path-validator.ts`). Every
+ *  `IndexEntry` reaching this primitive THROUGH THE CANONICAL PARSER
+ *  carries a `FilePath` value already free of `..`, `.`, empty segments,
+ *  and leading-slash absolute paths. However, the primitive is also
+ *  reachable from callers that construct `IndexEntry` records outside
+ *  the parser (test fixtures, in-memory adapters, future synthesisers).
+ *  Defence-in-depth: every entry is re-validated here so the primitive
+ *  stays safe even when the parser-trusted path is bypassed.
+ * - **Depth cap**: synthesis bounds recursion at `MAX_TREE_DEPTH` (4096,
+ *  matching git's canonical limit). The cap is enforced at the input
+ *  boundary by counting slashes — by the time recursion would catch a
+ *  pathological depth, the JS engine has already exhausted its call
+ *  stack. Path validation does NOT subsume this check: a path can be
+ *  safe segment-by-segment (no `..`/`.`/empty) and still be 10 000
+ *  levels deep.
+ */
 
-declare function writeObject(ctx: Context, object: GitObject): Promise<ObjectId>;
+/**
+ * Public entry: pass the `entries` array directly (typically
+ * `index.entries`, but callers holding a filtered list may supply it
+ * without wrapping in a fake `GitIndex`).
+ */
+declare const synthesizeTreeFromIndex: (ctx: Context, entries: ReadonlyArray<IndexEntry>) => Promise<ObjectId>;
 
 /**
- * Write a symbolic ref atomically. Used for HEAD updates that point at a
- * branch, branch renames affecting the current HEAD, and `clone`/`init`
- * to set the initial HEAD.
+ * Set `key` under `[section]` / `[section "subsection"]`, preserving every
+ * other byte verbatim.
  *
- * Single-level only in v1: target MUST be a direct ref name (no chained
- * symrefs). Validation runs through `validateRefName` for both `name` and
- * `target` — invalid inputs throw INVALID_REF before any I/O.
+ * - existing section with that key ⇒ its value is replaced;
+ * - existing section without that key ⇒ a `\t<key> = <value>` line is
+ *   inserted right after the header;
+ * - no such section ⇒ `[section]\n\t<key> = <value>\n` is appended.
+ */
+declare const setConfigEntry: (text: string, section: string, subsection: string | undefined, key: string, value: string) => string;
+/** `setConfigEntry` bound to the `[core]` section — kept for legacy callers. */
+declare const setCoreConfigEntry: (text: string, key: string, value: string) => string;
+/** One `key = value` write under `[section]` / `[section "subsection"]`. */
+interface ConfigEntry {
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Read `${gitDir}/config` (a missing file is treated as `''`), fold
+ * `setConfigEntry` over `entries`, write the result, and invalidate the
+ * per-`Context` `readConfig` cache so a later read sees the new values.
  */
-declare const writeSymbolicRef: (ctx: Context, name: RefName, target: RefName) => Promise<void>;
+declare const updateConfigEntries: (ctx: Context, entries: ReadonlyArray<ConfigEntry>) => Promise<void>;
+/** Fold a batch of `[core]` `key = value` writes via `updateConfigEntries`. */
+declare const updateCoreConfig: (ctx: Context, entries: Record<string, string>) => Promise<void>;
 
-declare function writeTree(ctx: Context, entries: ReadonlyArray<TreeEntry>): Promise<ObjectId>;
+/**
+ * Write the `.git/info/sparse-checkout` pattern file. The command tier
+ * computes the text (via `serializeCone` or raw non-cone lines); this
+ * primitive only persists it (design §7.3).
+ */
+
+/**
+ * Persist `text` to `.git/info/sparse-checkout`. The `.git/info` directory is
+ * created defensively first — `writeUtf8` creates parents on every adapter,
+ * but an explicit `mkdir` keeps the contract clear and survives adapters that
+ * tighten that guarantee.
+ */
+declare const writeSparsePatternText: (ctx: Context, text: string) => Promise<void>;
 
-export { MAX_COMMIT_MESSAGE_BYTES, MAX_INDEX_BYTES, MAX_PEEL_DEPTH, MAX_SYMBOLIC_REF_DEPTH, MAX_WALK_QUEUE_SIZE, MAX_WALK_SEEDS, TreeDiff, createCommit, diffTrees, getRepoRoot, mergeBase, readBlob, readIndex, readObject, readTree, resolveRef, updateRef, walkCommits, walkTree, writeObject, writeSymbolicRef, writeTree };
-export type { CreateCommitInput, DiffTreesInput, DiffTreesOptions, ReadObjectOptions, ResolveRefOptions, UpdateRefOptions, WalkCommitsOptions, WalkTreeEntry, WalkTreeOptions };
+export { MAX_SPARSE_PATTERN_FILE_BYTES, appendReflog, applyChangeset, buildIndexFromTree, buildPack, computeChangeset, deleteReflog, enumeratePushObjects, enumerateRefs, fetchPack, invalidateConfigCache, isWorkingTreeDirty, listReflogs, loadSparseMatcher, materializeTree, readConfig, readReflog, readShallow, readSparsePatternText, reflogExists, resolveReflogIdentity, setConfigEntry, setCoreConfigEntry, synthesizeTreeFromIndex, updateConfigEntries, updateCoreConfig, updateShallow, writeReflog, writeSparsePatternText };
+export type { ApplyChangesetOpts, ApplyChangesetResult, BuildIndexFromTreeOpts, BuildPackInput, BuildPackResult, Changeset, ChangesetEntry, ChangesetStats, ConfigEntry, EnumeratePushObjectsInput, FetchPackInput, FetchPackResult, MaterializeTreeOpts, MaterializeTreeResult, ParsedConfig };