@scolladon/tsgit 2.0.1 → 3.1.0

package/dist/types/chunks/index-Dqxddhav.d.cts

@@ -0,0 +1,1221 @@
+import { p as FileMode, aO as IndexEntry, G as GitIndex, B as BisectMidpoint, c as CatFileBatchOptions, C as CatFileBatchEntry, aN as ConfigScope, aP as ConfigKey, g as CreateCommitInput, h as CreateTagInput, n as DiffTreesInput, o as DiffTreesOptions, a3 as StatTreeDiff, a8 as TreeDiff, a7 as Tree, q as FlatTree, aR as TreeEntry, V as ReadObjectOptions, b as Blob, s as GitObject, a as AuthorIdentity, aQ as ReflogEntry, Y as ResolveRefOptions, aa as UpdateRefOptions, ac as WalkCommitsOptions, d as Commit, ab as WalkCommitsByDateOptions, ad as WalkSubmodulesOptions, a4 as SubmoduleEntry, af as WalkTreeOptions, ae as WalkTreeEntry, ah as WalkWorkingTreeOptions, ag as WalkWorkingTreeEntry } from './reflog-entry-Dy-O27Dd.cjs';
+import { F as FilePath, c as Context, O as ObjectId, R as RefName, j as HookName } from './context-CF1YF2S8.cjs';
+
+/**
+ * The four states a git attribute can resolve to (`gitattributes(5)`):
+ *
+ * - `true`          — set (`name`)
+ * - `false`         — unset (`-name`)
+ * - `'unspecified'` — explicitly unspecified (`!name`)
+ * - `{ set: value }`— set to a string value (`name=value`)
+ */
+type AttributeValue = true | false | 'unspecified' | {
+    readonly set: string;
+};
+
+/** A compiled glob — `test` reports whether a path matches the pattern. */
+interface GlobMatcher {
+    test(path: string): boolean;
+}
+
+/** A single `.gitattributes` pattern line and the attributes it assigns. */
+interface AttributeRule {
+    /** Pattern as written (post-unquote, pre-anchor-strip) — the round-trip source form. */
+    readonly pattern: string;
+    /** True when the pattern is anchored to the file's directory (leading or interior `/`). */
+    readonly anchored: boolean;
+    /** True when the pattern ends with `/` (directory-only). */
+    readonly directoryOnly: boolean;
+    /** 1-based source line number (tracks comment / blank gaps). */
+    readonly lineNumber: number;
+    /** Compiled glob, matched against a path relative to the source's basedir. */
+    readonly compiled: GlobMatcher;
+    /** Attribute assignments, last-token-wins within the line. */
+    readonly attributes: ReadonlyMap<string, AttributeValue>;
+}
+
+/** A macro name → the attributes it expands to. */
+type MacroRegistry = ReadonlyMap<string, ReadonlyMap<string, AttributeValue>>;
+
+/**
+ * One attributes file's rules, tagged with the directory it lives in. Patterns
+ * are matched against a path made relative to `basedir` (`''` is the repo root).
+ */
+interface AttributeSource {
+    readonly basedir: string;
+    readonly rules: ReadonlyArray<AttributeRule>;
+}
+
+/** Resolves the precedence-ordered attribute sources + macro registry for a path. */
+interface AttributeProvider {
+    readonly sourcesForPath: (path: FilePath) => Promise<{
+        readonly sources: ReadonlyArray<AttributeSource>;
+        readonly macros: MacroRegistry;
+    }>;
+}
+
+/** `true` ⇒ the path is in the sparse set (materialise it). */
+type SparseMatcher = (path: FilePath) => boolean;
+
+type WorkingTreeComparison = 'absent' | 'unchanged' | 'modified' | 'type-changed' | 'mode-changed';
+/**
+ * A working-tree comparison plus the working file's mode (`mW`). `worktreeMode`
+ * is what `git status --porcelain=v2` reports for the worktree side; it is
+ * present whenever a working file exists and omitted only when the file is
+ * `absent`. There is no working blob oid — the file need not be in the object
+ * store, so git itself prints no `hW`.
+ */
+interface WorkingTreeDelta {
+    readonly status: WorkingTreeComparison;
+    readonly worktreeMode?: FileMode;
+}
+declare const compareWorkingTreeDelta: (ctx: Context, entry: IndexEntry, provider?: AttributeProvider) => Promise<WorkingTreeDelta>;
+/**
+ * Enum projection over {@link compareWorkingTreeDelta} — the dirtiness verdict
+ * without the mode. Consumed by the local-modification valve (`rm`, `stash`,
+ * clean-work-tree, apply-merge) where only the status matters.
+ */
+declare const compareWorkingTreeEntry: (ctx: Context, entry: IndexEntry, provider?: AttributeProvider) => Promise<WorkingTreeComparison>;
+
+/**
+ * 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 ChangesetStats {
+    readonly add: number;
+    readonly update: number;
+    readonly delete: number;
+    readonly noop: number;
+}
+interface Changeset {
+    readonly entries: ReadonlyArray<ChangesetEntry>;
+    readonly stats: ChangesetStats;
+}
+interface TargetEntry {
+    readonly path: FilePath;
+    readonly id: ObjectId;
+    readonly mode: FileMode;
+}
+declare const computeChangeset: (currentIndex: GitIndex, targetTree: ReadonlyArray<TargetEntry>) => Changeset;
+
+interface ApplyChangesetOpts {
+    readonly changeset: Changeset;
+    readonly force: boolean;
+    readonly workdir: string;
+}
+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>;
+
+/**
+ * Compute the bisect midpoint: the commit that halves the candidate set
+ * (commits reachable from `bad` but not from any `good`).
+ *
+ * Returns `undefined` when the candidate set is empty (the bug does not
+ * exist within the `good`→`bad` range, or `bad` is already `good`-reachable).
+ *
+ * Mirrors `git rev-list --bisect-vars` semantics; see `BisectMidpoint`.
+ */
+declare const bisectMidpoint: (ctx: Context, good: ReadonlyArray<ObjectId>, bad: ObjectId) => Promise<BisectMidpoint | undefined>;
+
+/**
+ * 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 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;
+}
+declare const buildIndexFromTree: (ctx: Context, opts: BuildIndexFromTreeOpts) => Promise<ReadonlyArray<IndexEntry>>;
+
+interface BuildPackInput {
+    readonly oids: ReadonlyArray<ObjectId>;
+}
+interface BuildPackResult {
+    readonly bytes: Uint8Array;
+    /** Hex SHA of the pack body, also the trailer (last 20 bytes). */
+    readonly sha: string;
+    readonly objectCount: number;
+}
+declare const buildPack: (ctx: Context, input: BuildPackInput) => Promise<BuildPackResult>;
+
+declare function catFileBatch(ctx: Context, ids: AsyncIterable<ObjectId> | Iterable<ObjectId>, options?: CatFileBatchOptions): AsyncIterable<CatFileBatchEntry>;
+
+/** `push.default` mode; `tracking` is a deprecated alias canonicalized to `upstream` at parse time. */
+type PushDefaultMode = 'nothing' | 'current' | 'upstream' | 'simple' | 'matching';
+/**
+ * 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 attributesFile?: string;
+        readonly logAllRefUpdates?: boolean | 'always';
+        readonly hooksPath?: string;
+        /** `core.notesRef` — default notes ref when neither explicit arg nor `GIT_NOTES_REF` is set. */
+        readonly notesRef?: string;
+        readonly sparseCheckout?: boolean;
+        readonly sparseCheckoutCone?: boolean;
+        readonly looseCompression?: number;
+        /** `core.sshCommand` — shell string resolved by `resolveSshCommand` ahead of `GIT_SSH`. */
+        readonly sshCommand?: string;
+    };
+    readonly user?: {
+        readonly name?: string;
+        readonly email?: string;
+        readonly signingKey?: string;
+    };
+    readonly remote?: ReadonlyMap<string, {
+        readonly url?: string;
+        /** `remote.<name>.pushurl` — push-only URL; `push` reads `pushUrl ?? url`. */
+        readonly pushUrl?: 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;
+    }>;
+    /** `remote.pushDefault` — subsectionless `[remote]` only; per-remote `[remote "x"] pushDefault` is not read. */
+    readonly remotePushDefault?: string;
+    readonly branch?: ReadonlyMap<string, {
+        readonly remote?: string;
+        readonly merge?: string;
+        /** `branch.<name>.pushRemote` — overrides the push-remote for this branch. */
+        readonly pushRemote?: string;
+    }>;
+    /** `[submodule "<name>"]` — the registered (initialised) submodules. */
+    readonly submodule?: ReadonlyMap<string, {
+        readonly url?: string;
+        readonly active?: boolean;
+        readonly update?: string;
+    }>;
+    /** `[merge "<driver>"]` — configured custom merge drivers. */
+    readonly merge?: ReadonlyMap<string, {
+        readonly name?: string;
+        readonly driver?: string;
+        readonly recursive?: string;
+    }>;
+    /** `[diff "<name>"]` configured diff/textconv drivers. */
+    readonly diff?: ReadonlyMap<string, {
+        readonly textconv?: string;
+        readonly cachetextconv?: boolean;
+    }>;
+    /** `[filter "<name>"]` configured clean/smudge filter drivers. */
+    readonly filter?: ReadonlyMap<string, {
+        readonly clean?: string;
+        readonly smudge?: string;
+        readonly process?: string;
+        readonly required?: boolean;
+    }>;
+    /** `[extensions]` — `partialClone` names the promisor remote of a partial clone. */
+    readonly extensions?: {
+        readonly partialClone?: string;
+    };
+    /** `commit.gpgSign` — sign commits by default when true. */
+    readonly commit?: {
+        readonly gpgSign?: boolean;
+    };
+    /** `tag.gpgSign` — sign annotated tags by default when true. */
+    readonly tag?: {
+        readonly gpgSign?: boolean;
+    };
+    readonly push?: {
+        /** `push.gpgSign` — sign push certificates: `true`/`false`, or `if-asked` (server-requested). */
+        readonly gpgSign?: 'true' | 'false' | 'if-asked';
+        /** `push.default` — canonicalized push remote-selection mode (`tracking` maps to `upstream`). */
+        readonly default?: PushDefaultMode;
+    };
+    /** `[gpg]` — signing backend selection and the external program(s) invoked to sign/verify. */
+    readonly gpg?: {
+        readonly format?: 'openpgp' | 'ssh' | 'x509';
+        readonly program?: string;
+        /** `gpg.ssh.program` — the `ssh-keygen`-compatible binary used for `gpg.format = ssh`. */
+        readonly ssh?: {
+            readonly program?: 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 ValuelessEntry {
+    readonly key: string;
+    readonly source: string;
+    readonly line: number;
+}
+/**
+ * Valueless-entry detection: scan the repo-local config and return the FIRST
+ * valueless (`value === null`) entry, by config-file line, whose key
+ * (case-insensitive) is one of `keys` and which sits under `[<section> "<subsection>"]`
+ * (subsection `undefined` ⇒ the section with no subsection). Returns the fully-qualified
+ * key, the absolute config path, and the 1-based line, or `undefined` when no such
+ * entry exists. Walks the cached token stream, so an eager caller (the `[user]`
+ * identity pre-flight) pays only an in-memory scan, not a second read.
+ */
+declare const findFirstValuelessEntry: (ctx: Context, section: string, subsection: string | undefined, keys: ReadonlyArray<string>) => Promise<ValuelessEntry | undefined>;
+/**
+ * One `[section "subsection"]` block of a git-config-format INI file: the
+ * section name, an optional quoted subsection, and its key/value entries.
+ * Exported so `.gitmodules` parsing — byte-identical grammar — reuses one
+ * tokenizer (ADR-086).
+ *
+ * Entry `value`:
+ *   - `string` — key present with `=` (possibly `''` for `key =`)
+ *   - `null`   — key present with no `=` (git's internal NULL; boolean-true)
+ *   - `undefined` is never used here; the absent-key state lives one layer up
+ */
+interface IniSection {
+    readonly section: string;
+    readonly subsection: string | undefined;
+    readonly entries: ReadonlyArray<{
+        readonly key: string;
+        readonly value: string | null;
+    }>;
+}
+/**
+ * Tokenize git-config-format INI text into its sections. Lenient on structure,
+ * like git is with unknown keys: orphan key/values and malformed headers are
+ * skipped. Values follow git's full quoted-value grammar — quotes stripped,
+ * `\n`/`\t`/`\b`/`\"`/`\\` decoded, backslash-newline continuations, unquoted
+ * `#`/`;` starting comments — and a malformed value (unknown escape, unclosed
+ * quote) throws `CONFIG_PARSE_ERROR` with its 1-based physical line and the
+ * optional `source` label, mirroring git's `bad config line N in file F`
+ * refusal. A malformed quoted-subsection header (e.g. `[s"a"]`, `[s "a" x]`,
+ * unclosed quote) also throws `CONFIG_PARSE_ERROR` with `partialSectionName`.
+ *
+ * Keys before the first header are recorded under an implicit orphan section
+ * (`section: ''`, `subsection: undefined`), so they surface on the token stream
+ * and porcelain `--list`, mirroring git, which dumps them with no section prefix
+ * but refuses to address them. The orphan section is emitted only when it
+ * gathered an entry — a header-only file yields no leading empty section.
+ *
+ * A line with no `=` records a valueless key (`value: null`); the key grammar
+ * (alpha-first, `[a-zA-Z0-9-]`, then space/TAB and `=`-or-EOL) refuses anything
+ * else — `bad!key`, `9key`, a mid-key `#`/`;` — with `CONFIG_PARSE_ERROR`.
+ */
+declare const parseIniSections: (text: string, source?: string) => ReadonlyArray<IniSection>;
+
+/**
+ * Drop the per-scope sections cache for a single `Context`. Called by
+ * `invalidateConfigCache` in `config-read.ts` so writers can invalidate both
+ * caches atomically.
+ */
+declare const invalidateScopedConfigCache: (ctx: Context) => void;
+/**
+ * Read the raw IniSection array for a single config scope, or a scope-tagged
+ * flat array merged in precedence order (`system → global → local → worktree`)
+ * when `scope` is omitted.
+ *
+ * Per-Context, per-scope cached: a second call with the same `(ctx, scope)`
+ * shares the in-flight promise of the first. `invalidateConfigCache(ctx)` (from
+ * `config-read.ts`) drops the cached entries here too.
+ *
+ * In the merged-read path (`scope` omitted), scopes that are unavailable on
+ * the current adapter (`CONFIG_SCOPE_NOT_AVAILABLE`, `CONFIG_SYSTEM_PATH_UNRESOLVED`)
+ * are silently skipped — the caller gets whatever scopes the adapter can
+ * actually surface. Single-scope calls raise instead, so the caller can react
+ * to a missing scope explicitly.
+ */
+declare const readConfigSections: ({ ctx, scope, }: {
+    readonly ctx: Context;
+    readonly scope?: ConfigScope;
+}) => Promise<ReadonlyArray<{
+    readonly scope: ConfigScope;
+    readonly section: IniSection;
+}>>;
+/**
+ * Look up a single value for a fully-qualified key (`section.name` or
+ * `section.subsection.name`). Behaviour:
+ *
+ * - When `scope` is provided, reads only that scope. If the key has more than
+ *   one match in that scope, throws `CONFIG_MULTIPLE_VALUES` (carries `scope`).
+ * - When `scope` is omitted, merges across the four scopes. Same multi-value
+ *   throw if more than one entry matches anywhere across the merged view
+ *   (without the `scope` discriminator).
+ * - Absent key: returns `{ key, value: undefined }`; never throws.
+ * - Valueless key (no `=` in the file): returns `{ key, value: null, scope }`.
+ *   `null` (present, no `=`) is distinct from `undefined` (absent) and from
+ *   `''` (empty string after `key =`).
+ *
+ * Branding: the returned `key` is the caller's input cast to `ConfigKey`;
+ * `parseConfigKey` validates the string before this cast, so the brand is
+ * load-bearing only at the type level.
+ */
+declare const getConfigValue: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<{
+    readonly key: ConfigKey;
+    readonly value: string | null;
+    readonly scope: ConfigScope;
+} | {
+    readonly key: ConfigKey;
+    readonly value: undefined;
+}>;
+/**
+ * Look up every value for a key. Returns matches in scope-precedence order
+ * (and physical-file order within each scope). Empty array when the key is
+ * absent. Never throws on multi-value.
+ *
+ * Each `value` carries `string | null`: `null` means the entry was present
+ * with no `=` (git's internal NULL); `undefined` is never in the array.
+ */
+declare const getAllConfigValues: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<{
+    readonly key: ConfigKey;
+    readonly values: ReadonlyArray<{
+        readonly value: string | null;
+        readonly scope: ConfigScope;
+    }>;
+}>;
+
+declare function createCommit(ctx: Context, input: CreateCommitInput): Promise<ObjectId>;
+
+/**
+ * Build and write an annotated tag object (`object`/`type`/`tag`/`tagger` +
+ * message). Tag-name validity (non-empty, no `\n`/`\0`) is enforced by
+ * `serializeTagContent` during `writeObject`; the tagger identity is
+ * roundtripped through `serializeIdentity` here first (rejects control
+ * characters per Step 0(a)), matching `createCommit`'s author/committer
+ * validation.
+ */
+declare function createTag(ctx: Context, input: CreateTagInput): Promise<ObjectId>;
+
+declare function diffTrees(ctx: Context, a: DiffTreesInput, b: DiffTreesInput, options: DiffTreesOptions & {
+    withStat: true;
+}): Promise<StatTreeDiff>;
+declare function diffTrees(ctx: Context, a: DiffTreesInput, b: DiffTreesInput, options?: DiffTreesOptions): Promise<TreeDiff>;
+
+interface EnumerateObjectsOptions {
+    /** Include objects from pack files (default: true). */
+    readonly includePacks?: boolean;
+}
+declare function enumerateObjects(ctx: Context, opts?: EnumerateObjectsOptions): Promise<ReadonlyArray<ObjectId>>;
+
+/**
+ * push closure walker.
+ *
+ * Enumerates every object the remote does NOT have so the caller can
+ * stream them into `buildPack`. Walks commits from `wants` with `haves`
+ * as the boundary (canonical `until` semantics — the haves themselves
+ * are never yielded), then walks each commit's tree for the trees and
+ * blobs they reference. Duplicates are removed across the whole stream
+ * via a single `Set<ObjectId>`.
+ *
+ * Annotated tags pushed via a refspec must appear in the stream too —
+ * `readObject` is called on each want; if the result is a Tag, the tag
+ * oid is yielded and the chain is followed (tag → tag →... → commit)
+ * before handing the resolved commit oid to `walkCommits`.
+ *
+ * Gitlink entries in a tree (submodules) are NOT included: the oid
+ * names a commit that lives in another repository, which we cannot
+ * resolve locally and have no business including in this push's pack.
+ */
+
+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>;
+
+/**
+ * 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.
+ */
+
+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>;
+    /** 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;
+}
+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>;
+}
+interface PackDownload {
+    readonly packBytes: Uint8Array;
+    readonly shallow: ReadonlyArray<ObjectId>;
+    readonly unshallow: ReadonlyArray<ObjectId>;
+}
+/**
+ * Negotiates and drains the pack body for one `fetchPack` call. Callers bind
+ * the wire version and the transport session into this closure — `fetchPack`
+ * itself stays version-agnostic, matching every other caller of the shared
+ * `PackDownload` shape.
+ */
+type NegotiatePackBytes = (ctx: Context, input: FetchPackInput) => Promise<PackDownload>;
+declare const fetchPack: (ctx: Context, negotiatePackBytes: NegotiatePackBytes, input: FetchPackInput) => Promise<FetchPackResult>;
+
+/**
+ * Flatten a nested `Tree` into the `FlatTree` shape that the `mergeTrees`
+ * domain primitive (and the recursive tree-diff) consume.
+ *
+ * Bridges `walkTree`'s iterator into the `FlatTree` Map of
+ * `path → { id, mode }`. Accepts either an oid or an already-resolved `Tree`
+ * object (the recursive diff passes the latter to avoid a redundant root read);
+ * `walkTree` resolves both. Consumed by `merge.ts`'s clean-merge tree walk,
+ * `rm`'s HEAD-vs-index staged-change check, and the `diffTrees` recursive path,
+ * so it is exported from the primitives barrel.
+ *
+ * Pure with respect to the working tree — only reads git objects via
+ * `walkTree`.
+ */
+
+declare const flattenTree: (ctx: Context, treeIdOrObject: ObjectId | Tree) => Promise<FlatTree>;
+
+/**
+ * Local-only object-presence probe. A CQS query: unlike `readObject`, it never
+ * inflates, never verifies, and never consults `ctx.promisor` — a promised
+ * (not-yet-fetched) object in a partial repo answers `false` here, exactly as
+ * it would on disk. Callers that need the object's bytes still go through
+ * `readObject`.
+ */
+
+declare const hasObject: (ctx: Context, id: ObjectId) => Promise<boolean>;
+
+interface HashBlobOptions {
+    /** Persist the loose object under `.git/objects/<2>/<38>`. Default `false`. */
+    readonly write?: boolean;
+}
+declare const hashBlob: (ctx: Context, content: Uint8Array, opts?: HashBlobOptions) => Promise<ObjectId>;
+
+interface IsIgnoredQuery {
+    readonly path: FilePath;
+    /** Match directory rules (`build/`). Defaults to `false`. */
+    readonly isDirectory?: boolean;
+}
+interface IsIgnoredMatchSource {
+    readonly kind: 'global' | 'info' | 'gitignore';
+    /** POSIX-relative directory whose file carried the rule. `''` for global / info / repo-root gitignore. */
+    readonly basedir: FilePath | '';
+    /** 1-based line number of the matching rule inside its file. */
+    readonly line: number;
+    /** Raw pattern text (e.g. `*.log`, `!keep.log`, `build/`). */
+    readonly pattern: string;
+}
+interface IsIgnoredMatch {
+    readonly path: FilePath;
+    readonly ignored: boolean;
+    /** Set only when `ignored === true`. */
+    readonly source?: IsIgnoredMatchSource;
+}
+declare const isIgnored: (ctx: Context, queries: ReadonlyArray<IsIgnoredQuery>) => Promise<ReadonlyArray<IsIgnoredMatch>>;
+
+/**
+ * Lazily reads an on-disk fanout subtree's entries on demand. Injected by the
+ * caller so the trie stays pure: the I/O lives outside the domain.
+ */
+type SubtreeReader = (oid: ObjectId) => Promise<ReadonlyArray<TreeEntry>>;
+interface EmptySlot {
+    readonly kind: 'empty';
+}
+interface NoteSlot {
+    readonly kind: 'note';
+    readonly key: ObjectId;
+    readonly val: ObjectId;
+}
+interface SubtreeSlot {
+    readonly kind: 'subtree';
+    readonly prefix: string;
+    readonly oid: ObjectId;
+}
+interface InternalSlot {
+    readonly kind: 'internal';
+    readonly node: NotesTrie;
+}
+type Slot = EmptySlot | NoteSlot | SubtreeSlot | InternalSlot;
+/** A 16-way nibble-trie node: one slot per hex value of the oid at this depth. */
+interface NotesTrie {
+    readonly slots: ReadonlyArray<Slot>;
+    readonly preserved: ReadonlyArray<TreeEntry>;
+}
+
+interface LoadedNotesTree {
+    /** The trie built from the on-disk notes tree. Empty when the ref is absent. */
+    readonly trie: NotesTrie;
+    /** Reads a subtree's entries on demand (lazy subtree unpacking). */
+    readonly read: SubtreeReader;
+    /** The commit oid the notes ref resolved to, or `undefined` if the ref did not exist. */
+    readonly notesCommitOid: ObjectId | undefined;
+    /** The notes commit's root tree oid, or `undefined` if the ref did not exist. */
+    readonly notesTreeOid: ObjectId | undefined;
+}
+/**
+ * Resolves a notes ref to its commit, reads the commit's tree, and builds a
+ * `NotesTrie` via the domain's `loadTrieRoot`. Returns an empty trie when the
+ * ref does not exist yet.
+ *
+ * The returned `read` function acts as the lazy subtree reader: passing it to
+ * the domain's write-plan walker lets it unpack fanout subtrees on demand.
+ */
+declare function loadNotesTree(ctx: Context, ref: RefName): Promise<LoadedNotesTree>;
+
+/**
+ * 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.
+ *
+ * Returns the new IndexEntry list for the caller to commit, plus
+ * written/deleted counts. The primitive does NOT commit the index — the
+ * caller decides.
+ *
+ * ## 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.
+ */
+
+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>;
+
+declare const materializeWorktreeFromHead: (ctx: Context) => Promise<MaterializeTreeResult>;
+
+interface MergeBaseOptions {
+    readonly all?: boolean;
+    readonly octopus?: boolean;
+}
+/**
+ * Compute merge bases — the best common ancestors of the given commits.
+ *
+ * `commits[0]` is `one`, the rest are the others. Returns the lexicographically
+ * smallest single base by default; the full reduced set with `{ all: true }`;
+ * the octopus fold with `{ octopus: true }`. Unrelated histories yield `[]`.
+ */
+declare const mergeBase: (ctx: Context, commits: readonly ObjectId[], options?: MergeBaseOptions) => Promise<readonly ObjectId[]>;
+
+/**
+ * Pure path helpers composing `ctx.layout.gitDir` with known sub-paths.
+ * No I/O. No port access. Primitive step 3.
+ */
+
+/**
+ * Repository working-tree root. Returns the workDir from the current context;
+ * facade-tier code is responsible for discovery / realpath pinning
+ * at construction time. Primitives consume the already-resolved path.
+ */
+declare const getRepoRoot: (ctx: Context) => FilePath;
+declare const sparseCheckoutPath: (gitDir: string) => string;
+
+declare function readBlob(ctx: Context, id: ObjectId, options?: ReadObjectOptions): Promise<Blob>;
+
+/**
+ * Resolve HEAD's commit tree as a `FlatTree` (`path → { id, mode }`), or
+ * `undefined` for an unborn HEAD (no commits yet). This is git's HEAD-tree side
+ * of `diff-index` — the staged column compares it against the index.
+ *
+ * Tolerates an unborn HEAD by catching `REF_NOT_FOUND` (the symbolic ref points
+ * at a branch with no commit). A HEAD that resolves to a non-commit object is a
+ * corrupt repository and throws `unexpectedObjectType`.
+ *
+ * Pure with respect to the working tree — only reads git objects (via
+ * `resolveRef` / `readObject` / `flattenTree`).
+ */
+
+declare const readHeadTree: (ctx: Context) => Promise<FlatTree | undefined>;
+
+declare function readIndex(ctx: Context): Promise<GitIndex>;
+
+declare function readObject(ctx: Context, id: ObjectId, options?: ReadObjectOptions): Promise<GitObject>;
+
+/**
+ * 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;
+/**
+ * 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 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>;
+
+/**
+ * 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.
+ */
+
+/** 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>>;
+
+/** The default notes namespace git uses when no override is in effect. */
+declare const DEFAULT_NOTES_REF: RefName;
+/**
+ * Resolves the notes ref to use for a notes operation.
+ *
+ * Precedence (highest first):
+ *   1. Explicit `ref` argument (git `--ref`) — expanded under `refs/notes/`
+ *   2. `GIT_NOTES_REF` environment variable — verbatim, refused if outside
+ *   3. `core.notesRef` git config value — verbatim, refused if outside
+ *   4. `refs/notes/commits` (hard-coded default)
+ *
+ * The resolved name is validated as a legal ref name before being returned.
+ */
+declare function resolveNotesRef(ctx: Context, ref?: string): Promise<RefName>;
+
+declare function resolveRef(ctx: Context, name: RefName | 'HEAD', options?: ResolveRefOptions): Promise<ObjectId>;
+
+/** Optional arguments and stdin a caller threads into a hook invocation. */
+interface HookInput {
+    readonly args?: ReadonlyArray<string>;
+    readonly stdin?: string;
+}
+/**
+ * Run a blocking git hook through `ctx.hooks`. A no-op when no `HookRunner` is
+ * wired (browser, or opted out), when the hook file is absent / not executable
+ * (`skipped`), or when the hook exits 0. Throws `HOOK_FAILED` on a non-zero
+ * exit — the caller's signal to abort the operation.
+ */
+declare const runHook: (ctx: Context, name: HookName, input?: HookInput) => Promise<void>;
+/**
+ * Run an informational (`post-*`) git hook — fire-and-forget. The operation has
+ * already completed, so git ignores a post-hook's exit code (it cannot abort);
+ * tsgit does the same: absent runner, `skipped`, or any exit code → no throw,
+ * no return value. The runner never rejects, so this only ever resolves.
+ */
+declare const runInformationalHook: (ctx: Context, name: HookName, input?: HookInput) => Promise<void>;
+
+/**
+ * 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>;
+
+type SignPayloadResult = {
+    readonly ok: true;
+    readonly armor: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'off-node' | 'unsupported-format' | 'signer-failed';
+};
+interface SignRequest {
+    readonly format: 'openpgp' | 'ssh' | 'x509';
+    /** `gpg.program` / `gpg.ssh.program`; a family-specific default applies when absent. */
+    readonly program?: string;
+    /** Resolved `-u` value (openpgp) / `-f` key-file path (ssh). */
+    readonly selector: string;
+}
+interface ResolveSigningSelectorInput {
+    readonly signingKey?: string;
+    readonly keyOverride?: string;
+    readonly fallbackIdent: string;
+}
+/**
+ * Resolves the openpgp `-u` selector / the push-cert `pusher` selector —
+ * the identical `user.signingKey`-else-ident rule shared by commit, tag, and
+ * push-cert signing. The ssh `-f` key-file selector has NO ident fallback and
+ * is resolved by the caller directly (`keyOverride ?? signingKey`), not here.
+ */
+declare const resolveSigningSelector: (input: ResolveSigningSelectorInput) => string;
+/**
+ * Pure(ish) signing primitive delegating to the system signer through
+ * `ctx.command` — no new port. `gpg` runs stdin→stdout; `ssh-keygen` writes
+ * the payload to a temp file and reads the armor back from `<file>.sig`.
+ * Requesting `x509` and running with no `ctx.command` both refuse with a
+ * typed reason before any spawn or temp-file write. Success requires exit 0
+ * AND a well-formed armor block on the signer's output; anything else is a
+ * typed `signer-failed` refusal — never a partial or silent result.
+ */
+declare const signPayload: (ctx: Context, payload: Uint8Array, req: SignRequest) => Promise<SignPayloadResult>;
+
+interface StreamBlobOptions {
+    readonly verifyHash?: boolean;
+}
+interface BlobStream extends AsyncIterable<Uint8Array> {
+    readonly materialised: boolean;
+}
+declare function streamBlob(ctx: Context, id: ObjectId, options?: StreamBlobOptions): Promise<BlobStream>;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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>;
+
+/**
+ * Section-level surgery for `.git/config`: rename-section and remove-section.
+ * These operations match headers by their raw dotted name (byte-exact,
+ * case-sensitive) and rewrite or drop them without touching any other byte.
+ *
+ * @writes
+ *   surface: config
+ *   kind:    readback-only
+ *   format:  git-config-text
+ */
+
+/**
+ * Rename headers matching `oldName` (raw byte-exact dotted name) to the new
+ * section shape derived from `newName` (parsed via `parseNewSectionName`).
+ * The old name is never validated — any string is a legal lookup key; a miss
+ * throws `CONFIG_SECTION_NOT_FOUND` carrying the raw input verbatim. Throws
+ * `INVALID_OPTION` when the new subsection contains a LF or NUL.
+ */
+declare const renameConfigSection: ({ ctx, oldName, newName, scope, }: {
+    readonly ctx: Context;
+    readonly oldName: string;
+    readonly newName: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Delete headers matching `sectionName` (raw byte-exact dotted name) and their
+ * bodies. The name is never validated — any string is a legal lookup key (e.g.
+ * `'remote'`, `'s.'`, `''`); a miss throws `CONFIG_SECTION_NOT_FOUND` carrying
+ * the raw input verbatim. For the trailing-dot and empty-name forms see
+ * `rawSectionName` and `removeConfigSectionInText` documentation.
+ */
+declare const removeConfigSection: ({ ctx, sectionName, scope, }: {
+    readonly ctx: Context;
+    readonly sectionName: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+
+/**
+ * Targeted `.git/config` writer: entry-level surgery that preserves comments,
+ * blank lines, key order, casing of unrelated keys, and every other section
+ * byte-for-byte. Writes one `key = value` per call under any
+ * `[section]` / `[section "subsection"]`.
+ *
+ * @writes
+ *   surface: config
+ *   kind:    readback-only
+ *   format:  git-config-text
+ */
+
+/**
+ * Set `key` under `[section]` / `[section "subsection"]`, preserving every
+ * other byte verbatim.
+ *
+ * - existing section with that key ⇒ full span of the first match is replaced
+ *   by a single canonical `\t<key> = <value>` line;
+ * - existing section without that key ⇒ a `\t<key> = <value>` line is
+ *   inserted at the end of the last matching block;
+ * - no such section ⇒ `[section]\n\t<key> = <value>\n` is appended.
+ */
+declare const setConfigEntryInText: (text: string, section: string, subsection: string | undefined, key: string, value: string) => string;
+/** `setConfigEntryInText` bound to the `[core]` section — kept for legacy callers. */
+declare const setCoreConfigEntryInText: (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
+ * `setConfigEntryInText` over `entries`, write the result, and invalidate the
+ * per-`Context` `readConfig` cache so a later read sees the new values.
+ */
+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>;
+/**
+ * Mixed-operation batch entry. Folded over the on-disk text in order in
+ * a single `writeUtf8`. Use this when `remote` CRUD needs a section-
+ * remove paired with branch-referrer key removals in one atomic write.
+ */
+type ConfigOperation = {
+    readonly kind: 'set';
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+    readonly value: string;
+} | {
+    /**
+     * Insert a fresh `key = value` line at the end of the last matching
+     * section block WITHOUT replacing any existing entry with the same key.
+     * Use for multi-value keys (`fetch`) where every call must yield an
+     * additional line.
+     */
+    readonly kind: 'appendEntry';
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+    readonly value: string;
+} | {
+    /**
+     * Remove every entry span for `key` from the section, pruning the block
+     * header if no entries or comments remain. Delegates to `removeConfigEntry`.
+     */
+    readonly kind: 'removeEntry';
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+} | {
+    readonly kind: 'removeSection';
+    readonly section: string;
+    readonly subsection?: string;
+} | {
+    readonly kind: 'renameSection';
+    readonly section: string;
+    readonly from: string;
+    readonly to: string;
+};
+declare const applyConfigOpInText: (text: string, op: ConfigOperation) => string;
+/**
+ * Write a single `key = value` entry into the config file for the given scope
+ * (default `'local'`). Re-runs of the same call with a different value
+ * overwrite the existing entry in place (preserving comments and surrounding
+ * content). The key is validated via `parseConfigKey` (throws
+ * `CONFIG_KEY_INVALID` on a malformed input) and the value is validated by
+ * `assertValueSafe` (throws `CONFIG_VALUE_INVALID` on a banned control char)
+ * BEFORE any I/O — a rejected input never touches the file system.
+ *
+ * The branding on `ConfigKey` is enforced at the type level; this primitive
+ * accepts a raw string and parses it internally so it can be used directly
+ * from porcelain wrappers that hold un-branded callers' input.
+ */
+declare const setConfigEntry: ({ ctx, key, value, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly value: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Remove a single `key = value` entry from the given scope. Idempotent — if
+ * the key is absent the call is a no-op (no I/O). If the key appears more
+ * than once in the targeted scope, throws `CONFIG_MULTIPLE_VALUES` with
+ * `requested: 'remove'` (the caller should use `unsetAllConfigEntries` to
+ * clear every occurrence). An emptied section block is pruned entirely
+ * (header + blank lines removed) unless the block contains a comment.
+ */
+declare const unsetConfigEntry: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Remove every occurrence of `key` from the targeted scope. Idempotent — a
+ * missing key produces no I/O. Unlike `unsetConfigEntry`, multi-valued keys
+ * are explicitly supported: all matching spans are removed in a single
+ * read-modify-write pass. An emptied section block is pruned entirely
+ * (header + blank lines removed) unless the block contains a comment.
+ */
+declare const unsetAllConfigEntries: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+
+declare function updateRef(ctx: Context, name: RefName, newId: ObjectId, options: UpdateRefOptions): Promise<void>;
+
+declare function walkCommits(ctx: Context, options: WalkCommitsOptions): AsyncIterable<Commit>;
+
+/**
+ * Walk every commit reachable from `from` across **all** parents, yielding them
+ * in commit-date priority order — newest committer date first, oid-ascending on
+ * ties. A thin wrapper over the shared {@link commitDateWalk} core: it owns the
+ * public `INVALID_WALK_INPUT` seed contract (empty / too-many seeds) and
+ * delegates the all-parents traversal. The core's first-parent variant is
+ * internal — no public consumer needs date + first-parent yet (`log` routes
+ * `--first-parent` through `walkCommits`'s lazy FIFO).
+ */
+declare function walkCommitsByDate(ctx: Context, options: WalkCommitsByDateOptions): AsyncIterable<Commit>;
+
+/**
+ * Yield every gitlink reachable in `ref`'s tree, joined with its `.gitmodules`
+ * metadata. With `recursive: true`, descend into each nested submodule whose
+ * absorbed gitdir (`${gitDir}/modules/<name>`) is locally available; nested
+ * yields carry `depth >= 1` and a `parent` path. Uninitialised / missing /
+ * cyclic nested submodules contribute their own entry but no children — the
+ * absence of further yields is the signal, matching `git submodule status
+ * --recursive`.
+ */
+declare function walkSubmodules(ctx: Context, options?: WalkSubmodulesOptions): AsyncIterable<SubmoduleEntry>;
+
+declare function walkTree(ctx: Context, treeIdOrObject: ObjectId | Tree, options?: WalkTreeOptions): AsyncIterable<WalkTreeEntry>;
+
+/**
+ * Depth-first walk of the working tree starting at `ctx.layout.workDir`.
+ *
+ * Yields leaf entries (files and symlinks) as `{ path, stat }`. Directories
+ * are descended into, not yielded. `.git` at any level is skipped
+ * (case-insensitive, NTFS-trimmed). Embedded repositories (directories
+ * containing a `.git` child) are skipped entirely — yields nothing under
+ * them. Symlinks are surfaced via `lstat` (no follow); a symlink to a
+ * directory is yielded as a leaf, not descended into.
+ *
+ * The host repository's own `.git` is NOT treated as an embedded-repo
+ * marker — at the workDir root we only skip the `.git` entry itself, not
+ * the workDir.
+ */
+declare function walkWorkingTree(ctx: Context, options?: WalkWorkingTreeOptions): AsyncIterable<WalkWorkingTreeEntry>;
+
+interface WriteNotesTreeInput {
+    /** The in-memory trie to serialize. */
+    readonly trie: NotesTrie;
+    /** Subtree reader for lazy unpacking during write-plan generation. */
+    readonly read: SubtreeReader;
+    /** The notes commit the new commit should descend from, or `undefined` for a root commit. */
+    readonly prevCommitOid: ObjectId | undefined;
+    /** The notes commit message (caller owns the verb, e.g. "Notes added by 'git notes add'"). */
+    readonly message: string;
+    /** The identity used as both author and committer of the notes commit. */
+    readonly author: AuthorIdentity;
+}
+/**
+ * Converts a notes trie into a git commit:
+ *   1. Walks the trie to produce a flat write-plan.
+ *   2. Converts the flat plan into a real git tree hierarchy (bottom-up).
+ *   3. Creates a notes commit (author == committer == the caller-resolved identity).
+ *
+ * Identity resolution lives in the calling command (`resolveCurrentIdentity`);
+ * this primitive stays config-free. The caller is responsible for updating the
+ * notes ref and reflog after this returns.
+ */
+declare function writeNotesTree(ctx: Context, input: WriteNotesTreeInput): Promise<ObjectId>;
+
+declare function writeObject(ctx: Context, object: GitObject): 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).
+ *
+ * @writes
+ *   surface: sparseCheckoutFile
+ *   kind:    byte-identical
+ *   format:  git-sparse-checkout
+ */
+
+/**
+ * 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>;
+
+declare function writeTree(ctx: Context, entries: ReadonlyArray<TreeEntry>): Promise<ObjectId>;
+
+export { findFirstValuelessEntry as $, DEFAULT_NOTES_REF as D, buildPack as G, catFileBatch as J, compareWorkingTreeDelta as K, MAX_SPARSE_PATTERN_FILE_BYTES as M, compareWorkingTreeEntry as N, computeChangeset as O, createCommit as Q, createTag as R, deleteReflog as T, diffTrees as U, enumerateObjects as X, enumeratePushObjects as Y, enumerateRefs as Z, fetchPack as _, flattenTree as a0, getAllConfigValues as a1, getConfigValue as a2, getRepoRoot as a3, hasObject as a4, hashBlob as a5, invalidateConfigCache as a6, invalidateScopedConfigCache as a7, isIgnored as a8, isWorkingTreeDirty as a9, setConfigEntry as aA, setConfigEntryInText as aB, setCoreConfigEntryInText as aC, signPayload as aD, sparseCheckoutPath as aE, streamBlob as aF, synthesizeTreeFromIndex as aG, unsetAllConfigEntries as aH, unsetConfigEntry as aI, updateConfigEntries as aJ, updateCoreConfig as aK, updateRef as aL, updateShallow as aM, walkCommits as aN, walkCommitsByDate as aO, walkSubmodules as aP, walkTree as aQ, walkWorkingTree as aR, writeNotesTree as aS, writeObject as aT, writeReflog as aU, writeSparsePatternText as aV, writeTree as aW, listReflogs as aa, loadNotesTree as ab, loadSparseMatcher as ac, materializeTree as ad, materializeWorktreeFromHead as ae, mergeBase as af, parseIniSections as ag, readBlob as ah, readConfig as ai, readConfigSections as aj, readHeadTree as ak, readIndex as al, readObject as am, readReflog as an, readShallow as ao, readSparsePatternText as ap, readTree as aq, reflogExists as ar, removeConfigSection as as, renameConfigSection as at, resolveNotesRef as au, resolveRef as av, resolveReflogIdentity as aw, resolveSigningSelector as ax, runHook as ay, runInformationalHook as az, appendReflog as v, applyChangeset as w, applyConfigOpInText as x, bisectMidpoint as y, buildIndexFromTree as z };
+export type { ApplyChangesetOpts as A, BlobStream as B, Changeset as C, EnumerateObjectsOptions as E, FetchPackInput as F, HashBlobOptions as H, IniSection as I, LoadedNotesTree as L, ParsedConfig as P, SignPayloadResult as S, ValuelessEntry as V, WorkingTreeComparison as W, ApplyChangesetResult as a, GlobMatcher as aX, BuildIndexFromTreeOpts as b, BuildPackInput as c, BuildPackResult as d, ChangesetEntry as e, ChangesetStats as f, ConfigEntry as g, EnumeratePushObjectsInput as h, FetchPackResult as i, HookInput as j, IsIgnoredMatch as k, IsIgnoredMatchSource as l, IsIgnoredQuery as m, MaterializeTreeOpts as n, MaterializeTreeResult as o, MergeBaseOptions as p, PushDefaultMode as q, SignRequest as r, StreamBlobOptions as s, WorkingTreeDelta as t, WriteNotesTreeInput as u };