@scolladon/tsgit 2.0.1 → 3.0.0

package/dist/types/chunks/progress-Cp-huK45.d.cts

@@ -0,0 +1,1171 @@
+import { F as FilePath, R as RefName, O as ObjectId, j as HookName, H as HashConfig, c as Context, g as FileSystem, h as HashService, a as Compressor, P as ProgressReporter } from './context-D_A7-uau.cjs';
+import { aM as ConfigScope, o as FileMode, r as GitObject, G as GitIndex, aN as IndexEntry$1, k as DiffChange, L as LineKey, a6 as Tree } from './reflog-entry-BGJr9VfU.cjs';
+import { aQ as GlobMatcher } from './index-CMLLVz9B.cjs';
+import { b as HttpTransport } from './http-transport-DirKfK2S.cjs';
+
+interface RefStatus {
+    readonly name: string;
+    readonly accepted: boolean;
+    readonly reason?: string;
+}
+interface ReceivePackResponse {
+    readonly unpackOk: boolean;
+    readonly unpackError?: string;
+    readonly refUpdates: ReadonlyArray<RefStatus>;
+}
+
+type CommandError = {
+    readonly code: 'WORKING_TREE_DIRTY';
+    readonly localChanges: ReadonlyArray<FilePath>;
+    readonly untracked: ReadonlyArray<FilePath>;
+} | {
+    readonly code: 'PATHSPEC_NO_MATCH';
+    readonly pattern: string;
+} | {
+    readonly code: 'PATHSPEC_OUTSIDE_REPO';
+    readonly path: FilePath;
+} | {
+    readonly code: 'NOTHING_TO_COMMIT';
+} | {
+    readonly code: 'EMPTY_COMMIT_MESSAGE';
+} | {
+    readonly code: 'AUTHOR_UNCONFIGURED';
+} | {
+    readonly code: 'BRANCH_EXISTS';
+    readonly name: RefName;
+} | {
+    readonly code: 'BRANCH_NOT_FOUND';
+    readonly name: RefName;
+} | {
+    readonly code: 'TAG_EXISTS';
+    readonly name: RefName;
+} | {
+    readonly code: 'TAG_NOT_FOUND';
+    readonly name: RefName;
+} | {
+    readonly code: 'CANNOT_DELETE_CHECKED_OUT_BRANCH';
+    readonly name: RefName;
+} | {
+    readonly code: 'INVALID_URL';
+    readonly reason: string;
+} | {
+    readonly code: 'BLOCKED_HOST';
+    readonly host: string;
+    readonly reason: string;
+} | {
+    readonly code: 'TOO_MANY_REDIRECTS';
+    readonly count: number;
+} | {
+    readonly code: 'UNSUPPORTED_SCHEME';
+    readonly scheme: string;
+} | {
+    readonly code: 'TARGET_DIRECTORY_NOT_EMPTY';
+    readonly path: FilePath;
+} | {
+    readonly code: 'REMOTE_ADVERTISES_NO_REFS';
+} | {
+    readonly code: 'NO_PROMISOR_REMOTE';
+} | {
+    readonly code: 'NON_FAST_FORWARD';
+    readonly ref: RefName;
+    readonly local: ObjectId;
+    readonly remote: ObjectId;
+} | {
+    readonly code: 'PUSH_REJECTED';
+    readonly ref: RefName;
+    readonly reason: string;
+    readonly reportStatus: ReceivePackResponse;
+} | {
+    readonly code: 'MERGE_HAS_CONFLICTS';
+    readonly count: number;
+    readonly paths: ReadonlyArray<FilePath>;
+    readonly truncated?: boolean;
+} | {
+    readonly code: 'CHECKOUT_OVERWRITE_DIRTY';
+    readonly localChanges: ReadonlyArray<FilePath>;
+    readonly untracked: ReadonlyArray<FilePath>;
+} | {
+    readonly code: 'REVPARSE_AMBIGUOUS';
+    readonly expression: string;
+    readonly candidates: ReadonlyArray<ObjectId>;
+} | {
+    readonly code: 'REVPARSE_UNRESOLVED';
+    readonly expression: string;
+} | {
+    readonly code: 'PATH_NOT_IN_TREE';
+    readonly rev: string;
+    readonly path: string;
+} | {
+    readonly code: 'WORKTREE_FILE_ABSENT';
+    readonly path: string;
+} | {
+    readonly code: 'EMPTY_PATHSPEC';
+} | {
+    readonly code: 'OPERATION_IN_PROGRESS';
+    readonly operation: 'merge' | 'rebase' | 'cherry-pick' | 'revert';
+} | {
+    readonly code: 'NO_OPERATION_IN_PROGRESS';
+    readonly operation: 'merge' | 'rebase' | 'cherry-pick' | 'revert';
+} | {
+    readonly code: 'MAX_REFSPECS_EXCEEDED';
+    readonly count: number;
+    readonly limit: number;
+} | {
+    readonly code: 'REMOTE_NOT_CONFIGURED';
+    readonly remote: string;
+} | {
+    readonly code: 'NO_UPSTREAM_CONFIGURED';
+    readonly branch: RefName;
+} | {
+    readonly code: 'REMOTE_EXISTS';
+    readonly remote: string;
+} | {
+    readonly code: 'REMOTE_NAME_INVALID';
+    readonly name: string;
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_OPTION';
+    readonly option: string;
+    readonly reason: string;
+} | {
+    readonly code: 'REPOSITORY_DISPOSED';
+} | {
+    readonly code: 'ADAPTER_UNAVAILABLE';
+    readonly runtime: 'node' | 'browser' | 'memory';
+    readonly reason: string;
+} | {
+    readonly code: 'WORKING_TREE_FILE_TOO_LARGE';
+    readonly path: FilePath;
+    readonly size: number;
+    readonly limit: number;
+} | {
+    readonly code: 'GITIGNORE_FILE_TOO_LARGE';
+    readonly path: FilePath;
+    readonly size: number;
+    readonly limit: number;
+} | {
+    readonly code: 'GITATTRIBUTES_FILE_TOO_LARGE';
+    readonly path: FilePath;
+    readonly size: number;
+    readonly limit: number;
+} | {
+    readonly code: 'SPARSE_PATTERN_FILE_TOO_LARGE';
+    readonly path: FilePath;
+    readonly size: number;
+    readonly limit: number;
+} | {
+    readonly code: 'HOOK_FAILED';
+    readonly hook: HookName;
+    readonly exitCode: number;
+    readonly stderr: string;
+} | {
+    readonly code: 'CLEAN_FILTER_FAILED';
+    readonly path: FilePath;
+    readonly filter: string;
+    readonly exitCode: number;
+} | {
+    readonly code: 'SMUDGE_FILTER_FAILED';
+    readonly path: FilePath;
+    readonly filter: string;
+    readonly exitCode: number;
+} | {
+    readonly code: 'CONFIG_KEY_INVALID';
+    readonly key: string;
+    readonly reason: 'empty-section' | 'missing-name' | 'bad-character';
+    readonly position?: number;
+} | {
+    readonly code: 'CONFIG_VALUE_INVALID';
+    readonly key: string;
+    readonly reason: 'control-character';
+    readonly position: number;
+} | {
+    readonly code: 'CONFIG_PARSE_ERROR';
+    readonly line: number;
+    readonly source?: string;
+    readonly partialSectionName?: string;
+} | {
+    readonly code: 'CONFIG_MISSING_VALUE';
+    readonly key: string;
+    readonly source: string;
+    readonly line: number;
+} | {
+    readonly code: 'CONFIG_BAD_NUMERIC_VALUE';
+    readonly key: string;
+    readonly source: string;
+    readonly value: string;
+    readonly reason: 'invalid unit' | 'out of range';
+} | {
+    readonly code: 'CONFIG_BAD_ZLIB_LEVEL';
+    readonly level: number;
+} | {
+    readonly code: 'CONFIG_MULTIPLE_VALUES';
+    readonly key: string;
+    readonly count: number;
+    readonly requested: 'read' | 'overwrite' | 'remove';
+    readonly scope?: ConfigScope;
+} | {
+    readonly code: 'CONFIG_INVALID_FILE';
+    readonly sectionName: string;
+    readonly source: string;
+} | {
+    readonly code: 'CONFIG_SECTION_NOT_FOUND';
+    readonly name: string;
+    readonly scope: ConfigScope;
+} | {
+    readonly code: 'CONFIG_SCOPE_NOT_AVAILABLE';
+    readonly scope: ConfigScope;
+    readonly reason: 'browser-adapter' | 'worktree-extension-unset';
+} | {
+    readonly code: 'CONFIG_SYSTEM_PATH_UNRESOLVED';
+} | {
+    readonly code: 'MV_SOURCE_NOT_TRACKED';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_BAD_SOURCE';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_DESTINATION_EXISTS';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_INTO_SELF';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_DESTINATION_NOT_DIRECTORY';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_DESTINATION_DIRECTORY_MISSING';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_MULTIPLE_SOURCES_SAME_TARGET';
+    readonly source: FilePath;
+    readonly destination: FilePath;
+} | {
+    readonly code: 'MV_OVERLAPPING_SOURCES';
+    readonly child: FilePath;
+    readonly parent: FilePath;
+} | {
+    readonly code: 'RM_STAGED_CHANGES';
+    readonly paths: ReadonlyArray<FilePath>;
+} | {
+    readonly code: 'RM_LOCAL_MODIFICATIONS';
+    readonly paths: ReadonlyArray<FilePath>;
+} | {
+    readonly code: 'RM_STAGED_AND_LOCAL_CHANGES';
+    readonly paths: ReadonlyArray<FilePath>;
+} | {
+    readonly code: 'NO_INITIAL_COMMIT';
+} | {
+    readonly code: 'STASH_NOT_FOUND';
+    readonly index: number;
+    readonly stackSize: number;
+} | {
+    readonly code: 'STASH_APPLY_WOULD_OVERWRITE';
+    readonly paths: ReadonlyArray<FilePath>;
+} | {
+    readonly code: 'AMBIGUOUS_OID_PREFIX';
+    readonly prefix: string;
+    readonly candidates: ReadonlyArray<ObjectId>;
+} | {
+    readonly code: 'INVALID_SEQUENCER_TODO';
+    readonly reason: string;
+} | {
+    readonly code: 'CHERRY_PICK_MERGE_NO_MAINLINE';
+    readonly commit: ObjectId;
+} | {
+    readonly code: 'REVERT_MERGE_NO_MAINLINE';
+    readonly commit: ObjectId;
+} | {
+    readonly code: 'NO_NAMES';
+    readonly oid: ObjectId;
+} | {
+    readonly code: 'NO_ANNOTATED_NAMES';
+    readonly oid: ObjectId;
+} | {
+    readonly code: 'NO_REACHABLE_NAMES';
+    readonly oid: ObjectId;
+} | {
+    readonly code: 'NO_EXACT_MATCH';
+    readonly oid: ObjectId;
+} | {
+    readonly code: 'CANNOT_DESCRIBE';
+    readonly oid: ObjectId;
+} | {
+    readonly code: 'BUNDLE_EMPTY';
+    readonly reason: 'no-refs' | 'no-objects';
+} | {
+    readonly code: 'BUNDLE_READ_FAILED';
+    readonly path: string;
+} | {
+    readonly code: 'BUNDLE_BAD_HEADER';
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly code: 'BUNDLE_UNSUPPORTED_VERSION';
+    readonly path?: string;
+    readonly version: number;
+} | {
+    readonly code: 'BUNDLE_PREREQUISITE_NOT_COMMIT';
+    readonly oid: ObjectId;
+    readonly objectType: string;
+} | {
+    readonly code: 'NOTES_ALREADY_EXIST';
+    readonly object: ObjectId;
+} | {
+    readonly code: 'NOTES_OBJECT_HAS_NONE';
+    readonly object: ObjectId;
+} | {
+    readonly code: 'NOTES_REF_OUTSIDE';
+    readonly ref: string;
+};
+
+type DiffError = {
+    readonly code: 'INVALID_TREE_FOR_DIFF';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_DIFF_INPUT';
+    readonly reason: string;
+};
+declare const invalidTreeForDiff: (reason: string) => TsgitError;
+declare const invalidDiffInput: (reason: string) => TsgitError;
+
+type MergeError = {
+    readonly code: 'INVALID_MERGE_TREE';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_MERGE_INPUT';
+    readonly reason: string;
+};
+
+type ObjectType = 'blob' | 'tree' | 'commit' | 'tag';
+type DomainObjectError = {
+    readonly code: 'INVALID_OBJECT_ID';
+    readonly value: string;
+} | {
+    readonly code: 'INVALID_OBJECT_HEADER';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_TREE_ENTRY';
+    readonly offset: number;
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_COMMIT';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_TAG';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_FILE_MODE';
+    readonly value: string;
+} | {
+    readonly code: 'INVALID_IDENTITY';
+    readonly line: string;
+    readonly reason: string;
+} | {
+    readonly code: 'OBJECT_NOT_FOUND';
+    readonly id: ObjectId;
+} | {
+    readonly code: 'OBJECT_HASH_MISMATCH';
+    readonly expected: ObjectId;
+    readonly actual: ObjectId;
+} | {
+    readonly code: 'UNEXPECTED_OBJECT_TYPE';
+    readonly expected: ObjectType;
+    readonly actual: ObjectType;
+    readonly id: ObjectId;
+} | {
+    readonly code: 'TREE_CYCLE_DETECTED';
+    readonly id: ObjectId;
+} | {
+    readonly code: 'TREE_DEPTH_EXCEEDED';
+    readonly depth: number;
+} | {
+    readonly code: 'TREE_ENTRY_LIMIT_EXCEEDED';
+    readonly count: number;
+    readonly limit: number;
+} | {
+    readonly code: 'OBJECT_TOO_LARGE';
+    readonly id: ObjectId;
+    readonly actualSize: number;
+    readonly limit: number;
+};
+declare const invalidObjectId: (value: string) => TsgitError;
+declare const invalidObjectHeader: (reason: string) => TsgitError;
+declare const invalidTreeEntry: (offset: number, reason: string) => TsgitError;
+declare const invalidCommit: (reason: string) => TsgitError;
+declare const invalidTag: (reason: string) => TsgitError;
+declare const invalidFileMode: (value: string) => TsgitError;
+declare const invalidIdentity: (line: string, reason: string) => TsgitError;
+
+type ProtocolError = {
+    readonly code: 'INVALID_PKT_LENGTH';
+    readonly value: string;
+} | {
+    readonly code: 'PKT_LENGTH_RESERVED';
+    readonly value: number;
+} | {
+    readonly code: 'PKT_TOO_LARGE';
+    readonly value: number;
+} | {
+    readonly code: 'PKT_TRUNCATED';
+    readonly remaining: number;
+} | {
+    readonly code: 'INVALID_BASE_URL';
+    readonly reason: string;
+} | {
+    readonly code: 'MISSING_SERVICE_HEADER';
+    readonly expected: string;
+    readonly actual: string;
+} | {
+    readonly code: 'MISSING_CAPABILITIES';
+} | {
+    readonly code: 'INVALID_REF_LINE';
+    readonly line: string;
+} | {
+    readonly code: 'DUPLICATE_REF';
+    readonly name: string;
+} | {
+    readonly code: 'INVALID_SIDEBAND_CHANNEL';
+    readonly channel: number;
+} | {
+    readonly code: 'SIDEBAND_FATAL';
+    readonly message: string;
+} | {
+    readonly code: 'UNKNOWN_ACK_STATUS';
+    readonly value: string;
+} | {
+    readonly code: 'INVALID_REPORT_STATUS';
+    readonly line: string;
+} | {
+    readonly code: 'EMPTY_WANTS';
+} | {
+    readonly code: 'EMPTY_RECEIVE_UPDATES';
+} | {
+    readonly code: 'REFSPEC_INVALID';
+    readonly raw: string;
+    readonly reason: string;
+} | {
+    readonly code: 'TOO_MANY_ADVERTISED_REFS';
+    readonly count: number;
+    readonly limit: number;
+} | {
+    readonly code: 'INVALID_FILTER_SPEC';
+    readonly spec: string;
+    readonly reason: string;
+} | {
+    readonly code: 'REMOTE_FILTER_UNSUPPORTED';
+};
+
+type ReflogError = {
+    readonly code: 'INVALID_REFLOG_ENTRY';
+    readonly reason: string;
+} | {
+    readonly code: 'REFLOG_NOT_FOUND';
+    readonly ref: RefName;
+} | {
+    readonly code: 'REFLOG_ENTRY_OUT_OF_RANGE';
+    readonly ref: RefName;
+    readonly requested: number;
+    readonly available: number;
+};
+
+type RefsError = {
+    readonly code: 'INVALID_REF';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_PACKED_REFS';
+    readonly reason: string;
+} | {
+    readonly code: 'REF_NOT_FOUND';
+    readonly name: RefName;
+} | {
+    readonly code: 'REF_CHAIN_TOO_DEEP';
+    readonly depth: number;
+    readonly chain: ReadonlyArray<RefName>;
+} | {
+    readonly code: 'REF_CYCLE_DETECTED';
+    readonly chain: ReadonlyArray<RefName>;
+} | {
+    readonly code: 'REF_LOCKED';
+    readonly name: RefName;
+} | {
+    readonly code: 'REF_UPDATE_CONFLICT';
+    readonly name: RefName;
+    readonly expected: ObjectId | 'absent';
+    readonly actual: ObjectId | 'absent';
+};
+
+type RepositoryError = {
+    readonly code: 'NOT_A_REPOSITORY';
+    readonly path: FilePath;
+} | {
+    readonly code: 'BARE_REPOSITORY';
+    readonly operation: string;
+} | {
+    readonly code: 'ALREADY_INITIALIZED';
+    readonly path: FilePath;
+};
+
+/**
+ * Platform-abstracted stat shape for working-tree entries. Aligns with
+ * `src/ports/file-system.ts:FileStat` — `mtimeNs` and `ino` are optional so
+ * the browser adapter (which exposes neither) can satisfy the shape.
+ *
+ * `mode` is included so race detection covers chmod-only changes
+ * (executable-bit flips, permission tweaks). Racy-stat detection prefers
+ * `mtimeNs` when present, falls back to `mtimeMs`, and falls back further
+ * to SHA-trailer comparison for the index file specifically.
+ */
+interface WorkdirStat {
+    readonly mode: FileMode;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly mtimeNs?: bigint;
+    readonly ino?: bigint;
+}
+/**
+ * Pure data shape for a working-tree row. `kind` discriminates the four
+ * entry shapes the walker emits; the surfaced `mode` field mirrors
+ * `stat.mode` for ergonomic access.
+ */
+interface WorkdirEntryRow {
+    readonly source: 'workdir';
+    readonly path: FilePath;
+    readonly mode: FileMode;
+    readonly kind: 'file' | 'symlink' | 'directory' | 'submodule';
+    readonly stat: WorkdirStat;
+}
+
+type StorageError = {
+    readonly code: 'INVALID_PACK_HEADER';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_PACK_INDEX';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_PACK_ENTRY';
+    readonly offset: number;
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_DELTA';
+    readonly reason: string;
+} | {
+    readonly code: 'DELTA_CHAIN_TOO_DEEP';
+    readonly depth: number;
+};
+
+/** Submodule-tier error codes. */
+type SubmoduleError = {
+    readonly code: 'RELATIVE_URL_UNRESOLVABLE';
+    readonly url: string;
+} | {
+    readonly code: 'SUBMODULE_HAS_MODIFICATIONS';
+    readonly path: string;
+} | {
+    readonly code: 'SUBMODULE_PATH_EXISTS';
+    readonly path: string;
+};
+
+/** Worktree-tier error codes. */
+type WorktreeError = {
+    readonly code: 'WORKTREE_PATH_EXISTS';
+    readonly path: string;
+} | {
+    readonly code: 'BRANCH_CHECKED_OUT';
+    readonly branch: string;
+    readonly path: string;
+} | {
+    readonly code: 'WORKTREE_LOCKED';
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly code: 'WORKTREE_DIRTY';
+    readonly path: string;
+} | {
+    readonly code: 'NOT_A_WORKTREE';
+    readonly path: string;
+};
+
+type AdapterError = {
+    readonly code: 'FILE_NOT_FOUND';
+    readonly path: string;
+} | {
+    readonly code: 'FILE_EXISTS';
+    readonly path: string;
+} | {
+    readonly code: 'NOT_A_DIRECTORY';
+    readonly path: string;
+} | {
+    readonly code: 'DIRECTORY_NOT_EMPTY';
+    readonly path: string;
+} | {
+    readonly code: 'PERMISSION_DENIED';
+    readonly path: string;
+} | {
+    readonly code: 'UNSUPPORTED_OPERATION';
+    readonly operation: string;
+    readonly reason: string;
+} | {
+    readonly code: 'HASH_FAILED';
+    readonly reason: string;
+} | {
+    readonly code: 'COMPRESS_FAILED';
+    readonly reason: string;
+} | {
+    readonly code: 'DECOMPRESS_FAILED';
+    readonly reason: string;
+} | {
+    readonly code: 'HTTP_ERROR';
+    readonly statusCode: number;
+    readonly reason: string;
+} | {
+    readonly code: 'NETWORK_ERROR';
+    readonly reason: string;
+};
+/** Cross-cutting application-tier codes raised by primitives (not adapters). */
+type ApplicationError = {
+    readonly code: 'INVALID_WALK_INPUT';
+    readonly reason: string;
+} | {
+    readonly code: 'OPERATION_ABORTED';
+} | {
+    readonly code: 'RESOURCE_LOCKED';
+    readonly resource: 'index' | 'ref';
+    readonly path: string;
+    readonly mtimeMs?: number;
+} | {
+    readonly code: 'PACK_TOO_LARGE';
+    readonly objectCount: number;
+    readonly limit: number;
+} | {
+    readonly code: 'SNAPSHOT_REQUIRED';
+    readonly reason: string;
+} | {
+    readonly code: 'WORKDIR_RACE';
+    readonly path: string;
+    readonly observed: WorkdirStat;
+    readonly current: WorkdirStat;
+} | {
+    readonly code: 'ORDER_INVARIANT_VIOLATION';
+    readonly previous: string;
+    readonly current: string;
+};
+type TsgitErrorData = DomainObjectError | StorageError | RefsError | ReflogError | IndexError | AdapterError | DiffError | MergeError | ApplicationError | ProtocolError | RepositoryError | CommandError | SubmoduleError | WorktreeError;
+declare class TsgitError extends Error {
+    readonly data: TsgitErrorData;
+    readonly name = "TsgitError";
+    constructor(data: TsgitErrorData);
+}
+
+type IndexError = {
+    readonly code: 'INVALID_INDEX_HEADER';
+    readonly reason: string;
+} | {
+    readonly code: 'INVALID_INDEX_ENTRY';
+    readonly offset: number;
+    readonly reason: string;
+};
+declare const invalidIndexHeader: (reason: string) => TsgitError;
+declare const invalidIndexEntry: (offset: number, reason: string) => TsgitError;
+
+declare const stripspace: (message: string) => string;
+
+declare function bytesToHex(bytes: Uint8Array): string;
+declare function hexToBytes(hex: string): Uint8Array;
+declare function compareBytes(a: Uint8Array, b: Uint8Array): number;
+
+/**
+ * Length in bytes of an object's canonical payload — the body that follows
+ * `<type> <size>\0` on disk. Equal to the `size` field of git's
+ * `cat-file --batch` header.
+ *
+ * Blobs are O(1) (a slice of an existing buffer). Trees / commits / tags
+ * re-serialise the body to measure it; that matches the cost of
+ * `serializeObject` and is the price of not threading the on-disk size
+ * through the read pipeline. Acceptable for v1 — see
+ * `docs/design/cat-file-batch.md` §4.1.
+ */
+declare const payloadByteLength: (object: GitObject, hash: HashConfig) => number;
+
+declare function parseIndex(bytes: Uint8Array): GitIndex;
+
+/**
+ * Lexicographic comparator for index entries. Git stores entries
+ * byte-sorted by path; this returns the standard `-1 / 0 / +1` triple so
+ * `Array.prototype.sort` produces ascending path order and leaves
+ * equal-path entries in their original (stable) order.
+ */
+declare function compareEntryPath(a: IndexEntry$1, b: IndexEntry$1): number;
+declare function serializeIndex(index: GitIndex): Uint8Array;
+
+type ModeKind = 'file' | 'symlink' | 'directory' | 'gitlink';
+declare function kindOf(mode: FileMode): ModeKind;
+declare function isSameKind(a: FileMode, b: FileMode): boolean;
+declare function isGitlink(mode: FileMode): boolean;
+
+interface PatchFile {
+    readonly change: DiffChange;
+    readonly oldContent?: Uint8Array;
+    readonly newContent?: Uint8Array;
+    /** Override the binary-vs-text decision for the PATCH surface. `'binary'` forces the
+     *  `Binary files … differ` / binary-body branch; `'text'` forces the text-hunk branch
+     *  even over NUL content; `undefined` uses the default `isBinary` content-sniff. */
+    readonly patchBinaryOverride?: 'binary' | 'text';
+    /** Override the numstat decision (consumed by computeStatFields via diff-trees, NOT by
+     *  this serializer). Carried on PatchFile so a single resolve pass attaches both. */
+    readonly numstatBinaryOverride?: 'binary' | 'text';
+}
+interface PatchPathPrefix {
+    readonly old: string;
+    readonly new: string;
+}
+interface PatchOptions {
+    readonly contextLines?: number;
+    readonly pathPrefix?: PatchPathPrefix;
+    readonly lineKey?: LineKey;
+    readonly ignoreBlankLines?: boolean;
+}
+interface EmitOptions {
+    readonly lineKey?: LineKey;
+    readonly ignoreBlankLines?: boolean;
+}
+type EditKind = 'context' | 'delete' | 'insert';
+interface BodyLine {
+    readonly kind: EditKind;
+    readonly text: string;
+    readonly trailingNoNewline: boolean;
+}
+interface OutputHunk {
+    readonly oldStart: number;
+    readonly oldLen: number;
+    readonly newStart: number;
+    readonly newLen: number;
+    readonly body: ReadonlyArray<BodyLine>;
+}
+/**
+ * Group the line-level diff of two blobs into unified-diff hunks (the shared
+ * core behind both the unified-diff serializer and range-diff's `## ` text). Each
+ * hunk carries its old/new line spans and a typed body (`context`/`delete`/
+ * `insert`). The `@@ -a,b +c,d @@` line numbers and the body prefixes are the
+ * caller's to render.
+ */
+declare function computeHunks(oldBytes: Uint8Array, newBytes: Uint8Array, contextLines: number, options?: EmitOptions): ReadonlyArray<OutputHunk>;
+declare function renderPatch(files: ReadonlyArray<PatchFile>, opts?: PatchOptions): string;
+
+declare function comparePaths(a: FilePath, b: FilePath): number;
+declare function sortByPath<T>(items: ReadonlyArray<T>, pathOf: (item: T) => FilePath): T[];
+
+interface PathspecEntry {
+    /** Original raw pattern (including any leading `!`), for diagnostics. */
+    readonly pattern: string;
+    /** Pattern with the leading `!` (if any) stripped — the part that compiled to `compiled`. */
+    readonly body: string;
+    /** True when the original pattern started with `!`. */
+    readonly negated: boolean;
+    /**
+     * True when the body (post-`!`) contains no glob metacharacters.
+     * Literal entries match the exact path AND any descendant — Git's
+     * `git add src` semantics where `src` covers everything under it.
+     */
+    readonly isLiteral: boolean;
+    /** Compiled glob matcher. Always tested against the candidate path verbatim. */
+    readonly compiled: GlobMatcher;
+}
+type Pathspec = ReadonlyArray<PathspecEntry>;
+
+/**
+ * Three index-entry boolean flags lifted out of git's wire format. Each is
+ * a real index attribute; they collectively cover the bits status / add /
+ * checkout consult.
+ *
+ * - `assumeUnchanged` (git-update-index `--assume-unchanged`): the user has
+ *   promised the file does not change; tools may skip stat checks.
+ * - `skipWorktree` (sparse-checkout): the file is tracked but should not be
+ *   materialized in the working tree.
+ * - `intentToAdd` (`git add --intent-to-add`): the entry exists with mode +
+ *   path but its content has not yet been staged; oid is the empty blob.
+ */
+interface IndexFlags {
+    readonly assumeUnchanged: boolean;
+    readonly skipWorktree: boolean;
+    readonly intentToAdd: boolean;
+}
+/**
+ * Stat snapshot persisted alongside each index entry by git's stat-cache.
+ * May be stale (the file may have been modified since the index was
+ * written); validity is determined by comparing against a fresh `lstat`
+ * per git's racy-stat rules. Fields mirror the optional-precision shape
+ * already used by `src/ports/file-system.ts:FileStat`.
+ */
+interface IndexCachedStat {
+    readonly mtimeMs: number;
+    readonly mtimeNs?: bigint;
+    readonly size: number;
+    readonly ino?: bigint;
+}
+/**
+ * Pure data shape for an index-source row. Stage > 0 means the entry is
+ * part of an unmerged path (1 = base, 2 = ours, 3 = theirs); stage 0 is
+ * the resolved / normal entry.
+ */
+interface IndexEntryRow {
+    readonly source: 'index';
+    readonly path: FilePath;
+    readonly oid: ObjectId;
+    readonly mode: FileMode;
+    readonly stage: 0 | 1 | 2 | 3;
+    readonly flags: IndexFlags;
+    readonly cachedStat?: IndexCachedStat;
+}
+
+/**
+ * Extracts the entry shape `E` from a `Snapshot<E>` constraint. Used by
+ * the join row types to project each slot's entry shape onto the merged
+ * row.
+ */
+type EntryOf<X> = X extends {
+    entries(opts?: unknown): AsyncIterable<infer E>;
+} ? E : never;
+/**
+ * Outer-join row — `path` is mandatory, every named slot is OPTIONAL.
+ * A slot is `undefined` for rows where that source did not contribute
+ * an entry at the given path.
+ */
+type OuterJoinRow<S> = {
+    readonly path: FilePath;
+} & {
+    readonly [K in keyof S]?: EntryOf<S[K]>;
+};
+/**
+ * Inner-join row — `path` is mandatory and every named slot is REQUIRED
+ * (no `?`). Only rows where every source contributed an entry at the
+ * given path are emitted.
+ */
+type InnerJoinRow<S> = {
+    readonly path: FilePath;
+} & {
+    readonly [K in keyof S]: EntryOf<S[K]>;
+};
+
+/**
+ * Discriminator for snapshot sources. Each `Snapshot` handle carries a
+ * `kind` field so consumers can dispatch on the underlying source at
+ * runtime (matching the static discriminator on the entry's `source` field).
+ *
+ * Compound state heads (`mergeHead`, `cherryPickHead`, etc.) resolve to a
+ * tree but advertise their own kind so callers can distinguish a
+ * fresh-cloned `head` from a `mergeHead` at the snapshot-handle level.
+ */
+type SnapshotKind = 'tree' | 'commit' | 'index' | 'workdir' | 'mergeHead' | 'cherryPickHead' | 'revertHead' | 'fetchHead' | 'stash';
+
+/**
+ * Pure data shape for a tree-source row. Carried inside `TreeEntry`
+ * (application tier) which adds I/O methods. Domain layering rule:
+ * this file has zero outward imports beyond `domain/objects/`.
+ */
+interface TreeEntryRow {
+    readonly source: 'tree';
+    readonly path: FilePath;
+    readonly oid: ObjectId;
+    readonly mode: FileMode;
+    readonly kind: 'file' | 'symlink' | 'submodule';
+}
+
+/**
+ * Options shared by every resolver port. The `bypassCache` flag asks a
+ * caching adapter to skip its cache for this call; raw adapters ignore it.
+ */
+interface ResolveOptions {
+    readonly bypassCache?: boolean;
+}
+/**
+ * Predicate used by `WorkdirEnumerator` to prune working-tree traversal.
+ * Mirrors the existing `WalkIgnorePredicate` shape (14.3) so the same
+ * `repo.ignoreMatcher()` builder can be used at both the legacy walker
+ * surface and the new snapshot surface.
+ *
+ * Invoked on every directory BEFORE descent (returning `true` prunes the
+ * entire subtree, skipping its `lstat` cost) and on every leaf BEFORE
+ * yielding (returning `true` drops the leaf). Composes with `paths`
+ * (pathspec inclusion filter) via logical AND.
+ */
+type WalkIgnorePredicate = (path: FilePath, isDirectory: boolean) => boolean | Promise<boolean>;
+/**
+ * Options for `WorkdirEnumerator.enumerate`. The snapshot layer translates
+ * `WorkdirSnapshotOptions` (which carries higher-level concerns like
+ * `consistency`) down to this shape; the enumerator port itself stays
+ * focused on what to enumerate.
+ */
+interface WorkdirEnumOptions {
+    readonly paths?: Pathspec;
+    readonly excludes?: WalkIgnorePredicate;
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Resolves `.git/index` to its parsed `GitIndex` structure. Caching
+ * adapters (see `src/adapters/snapshot-resolvers/caching-index-resolver.ts`)
+ * implement freshness via the `WriteEventStream` + `GenerationView` ports;
+ * raw adapters parse on every call.
+ *
+ * Callers MUST treat the returned value as deeply frozen — implementations
+ * are free to share the same `GitIndex` reference across calls.
+ */
+interface IndexResolver {
+    resolve(ctx: Context, opts?: ResolveOptions): Promise<GitIndex>;
+}
+/**
+ * Resolves a tree object by its oid. Caching adapters use a content-addressed
+ * LRU (oids are immutable, no invalidation needed). Throws on type
+ * mismatch — the oid must address a tree.
+ */
+interface TreeResolver {
+    resolve(ctx: Context, treeId: ObjectId, opts?: ResolveOptions): Promise<Tree>;
+}
+/**
+ * Streams working-tree entries in canonical git path order. Honors
+ * `ctx.signal` and the optional `opts.signal`; aborts surface as
+ * `operationAborted()` from the iterator.
+ */
+interface WorkdirEnumerator {
+    enumerate(ctx: Context, opts: WorkdirEnumOptions): AsyncIterable<WorkdirEntryRow>;
+}
+
+/**
+ * Application-tier wrapper around `IndexEntryRow`. Inherits the sync data
+ * fields (path/oid/mode/stage/flags/cachedStat) and adds `read()`, which
+ * pulls the blob bytes by oid via the existing object resolver chain.
+ *
+ * Index entries' `cachedStat` reflects the index's stat-cache; it MAY
+ * disagree with the live filesystem. Consumers that need fresh stat
+ * data should consult a `WorkdirSnapshot` instead.
+ */
+interface IndexEntry extends IndexEntryRow {
+    read(): Promise<Uint8Array>;
+}
+
+/**
+ * Application-tier wrapper around `TreeEntryRow`. Inherits the sync data
+ * fields (path/oid/mode/kind) and adds the I/O method `read()`, which
+ * pulls the blob bytes for this entry's oid via the existing object
+ * resolver chain.
+ *
+ * Each entry binds to the `Context` it was created with. Holding an entry
+ * past its context's lifetime is undefined — the resolver may reject the
+ * read with an aborted-operation error if the context's signal fires.
+ */
+interface TreeEntry extends TreeEntryRow {
+    read(): Promise<Uint8Array>;
+}
+
+/**
+ * Discriminator for write-target categories used across the CQS port triple
+ * — `WriteEventEmitter` (command), `WriteEventStream` (subscribe), and
+ * `GenerationView` (query). See ADR-157 for the rationale of splitting
+ * those three concerns across separate port files; `WriteScope` lives in
+ * its own file so none of the three ports needs to import another's
+ * declaration, preserving the CQS split at the import-graph level.
+ */
+type WriteScope = 'index' | 'refs' | 'objects';
+
+/**
+ * Query side of the write-event triple (ADR-157). Read primitives depend on
+ * this interface only — they query the current generation per scope but
+ * cannot emit or subscribe.
+ *
+ * `current(scope)` is monotonic per scope: each successful `WriteEventEmitter.emit(scope)`
+ * increments the corresponding counter exactly once. Scopes are independent
+ * — `emit('index')` does not affect `current('refs')` or `current('objects')`.
+ */
+interface GenerationView {
+    current(scope: WriteScope): number;
+}
+
+/**
+ * Command side of the write-event triple (ADR-157). Write-boundary primitives
+ * depend on this interface only — they cannot observe events, only emit them.
+ *
+ * Implementations MUST be called AFTER a successful write but BEFORE
+ * releasing any acquired lock. See `docs/understand/caching.md` for the
+ * lock-ordering protocol; in-process readers rely on the
+ * emit-before-release ordering to avoid TOCTOU windows.
+ */
+interface WriteEventEmitter {
+    emit(scope: WriteScope): void;
+}
+
+/**
+ * Disposable handle returned from `WriteEventStream.subscribe`. Matches the
+ * shape of TC39 Explicit Resource Management's `Disposable` so callers can
+ * use `using` syntax once the project's TS target supports it.
+ */
+interface Disposable {
+    dispose(): void;
+}
+/**
+ * Subscribe side of the write-event triple (ADR-157). Cache adapters depend
+ * on this interface only — they observe events but cannot emit them.
+ *
+ * Subscribers receive identical event sequences regardless of subscription
+ * order. Disposing a subscription removes the listener; the next event is
+ * not delivered to that listener.
+ */
+interface WriteEventStream {
+    subscribe(listener: (scope: WriteScope) => void): Disposable;
+}
+
+/**
+ * Application-tier wrapper around `WorkdirEntryRow`. Inherits the sync
+ * data fields (path/mode/kind/stat) and adds four named I/O methods:
+ *
+ * - `hash()`  — reads the file, computes its blob-hash (`blob <size>\0` +
+ *               bytes hashed by `ctx.hash`). For a symlink, hashes the
+ *               link target bytes (git's convention).
+ * - `read()`  — raw file bytes (no hash). For a symlink, returns the
+ *               target as UTF-8 bytes.
+ * - `readLink()` — symlink target string. Throws `UNSUPPORTED_OPERATION`
+ *               when `kind !== 'symlink'`.
+ * - `verify()` — re-`lstat`s the entry; throws `WORKDIR_RACE` if any
+ *               of `(mode, size, mtimeMs)` differs from the row's
+ *               original stat. The opt-in race-detection hook for
+ *               `add -p` / `checkout --detect-races` style callers.
+ *
+ * Each entry binds to the `Context` it was created with; the absolute
+ * workdir path is computed once at creation and shared by every method.
+ */
+interface WorkdirEntry extends WorkdirEntryRow {
+    hash(): Promise<ObjectId>;
+    read(): Promise<Uint8Array>;
+    readLink(): Promise<string>;
+    verify(): Promise<void>;
+}
+
+/**
+ * Lazy, atomic-iteration view of a row source (tree / index / workdir / …).
+ * Snapshots are descriptions, not data — no I/O happens until the consumer
+ * starts iterating. See design §8 and ADR-149.
+ *
+ * Iteration-stability invariant: once a snapshot's `entries()` resolves its
+ * underlying source on the first iteration, every subsequent iteration on
+ * the same handle replays from that captured source. Concurrent writes
+ * routed through `WriteEventEmitter.emit(scope)` invalidate the underlying
+ * resolver cache for *new* snapshots but never disturb in-flight iterations.
+ */
+interface Snapshot<E extends SnapshotEntry> {
+    readonly kind: SnapshotKind;
+    entries(opts?: SnapshotOptions): AsyncIterable<E>;
+}
+type SnapshotEntry = TreeEntry | IndexEntry | WorkdirEntry;
+type TreeSnapshot = Snapshot<TreeEntry>;
+type IndexSnapshot = Snapshot<IndexEntry>;
+type WorkdirSnapshot = Snapshot<WorkdirEntry>;
+interface SnapshotOptions {
+    readonly paths?: Pathspec;
+    readonly recurse?: boolean;
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+    readonly bypassCache?: boolean;
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * A point-in-time view of a stash entry. The trio (index, workdir,
+ * untracked) is exposed as plain properties — discoverable at hand-out
+ * time, not behind a method (ADR-156 + design §9.1).
+ *
+ * `untracked` is `null` when the stash was created without
+ * `--include-untracked`. Consumers branch on the property's value, not
+ * on whether a method exists.
+ */
+interface StashSnapshot {
+    readonly kind: 'stash';
+    readonly index: TreeSnapshot;
+    readonly workdir: TreeSnapshot;
+    readonly untracked: TreeSnapshot | null;
+}
+
+interface WorkdirSnapshotOptions extends SnapshotOptions {
+    readonly excludes?: WalkIgnorePredicate;
+    readonly consistency?: 'eager' | 'verified';
+}
+
+interface SnapshotFactory {
+    head(opts?: SnapshotOptions): TreeSnapshot;
+    commit(oid: ObjectId, opts?: SnapshotOptions): TreeSnapshot;
+    tree(oid: ObjectId, opts?: SnapshotOptions): TreeSnapshot;
+    index(opts?: SnapshotOptions): IndexSnapshot;
+    workdir(opts?: WorkdirSnapshotOptions): WorkdirSnapshot;
+    mergeHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    cherryPickHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    revertHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    fetchHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    stashEntry(stashIndex: number, opts?: SnapshotOptions): Promise<StashSnapshot | null>;
+}
+
+/**
+ * The four adapter ports the facade plumbs into the Context. Each runtime
+ * shim (`index.node.ts`, `index.browser.ts`, `index.default.ts` — wired in
+ * Step 5) provides a `detectAdapter(): AdapterSet` that returns the runtime-
+ * appropriate set.
+ */
+interface AdapterSet {
+    readonly fs: FileSystem;
+    readonly hash: HashService;
+    readonly compressor: Compressor;
+    readonly transport: HttpTransport;
+}
+/**
+ * Prototype-pollution-safe runtime check. Returns true only when `process` is
+ * an object that owns BOTH `versions` and `versions.node` as own properties —
+ * an attacker who pollutes `Object.prototype.versions` cannot make this
+ * return true.
+ *
+ * Used as a manual fallback only; the primary detection mechanism is
+ * `package.json` conditional exports (resolved at bundle time, immune to
+ * runtime pollution).
+ */
+declare const isNode: () => boolean;
+/**
+ * Returns true when both `window` and `navigator` exist AS OWN globals on
+ * `globalThis` AND have non-undefined values. Two-stage check:
+ * - `hasOwn` rejects properties inherited from a polluted `Object.prototype`.
+ * - `typeof` rejects own properties that have been assigned `undefined`
+ *   (e.g., test harnesses that stub the global to undefined).
+ */
+declare const isBrowser: () => boolean;
+/**
+ * Three-way runtime classification used by manual call sites. Node takes
+ * precedence over browser when both look present (e.g., test environments
+ * with jsdom + a real Node process).
+ */
+declare const detectRuntime: () => "node" | "browser" | "memory";
+
+/** No-op reporter — default when the caller does not provide one. */
+declare const noopProgress: ProgressReporter;
+/**
+ * Built-in reporter that emits one line per call to a user-supplied `sink`.
+ *
+ * Format:
+ *   start(op)             → "<safeOp>: start"
+ *   start(op, total)      → "<safeOp>: start/<total>"
+ *   update(op, c)         → "<safeOp>: <c>"
+ *   update(op, c, t)      → "<safeOp>: <c>/<t>"
+ *   update(op, c, t, txt) → "<safeOp>: <c>/<t> <safeText>"
+ *   end(op)               → "<safeOp>: done"
+ *
+ * `op` is sanitized identically to `text` (defense-in-depth: a programming bug
+ * that wires a sideband-derived string into `op` cannot inject control characters).
+ *
+ * A throwing `sink` cannot crash the reporter — every call is wrapped in
+ * try/catch.
+ */
+declare const consoleProgress: (sink: (line: string) => void) => ProgressReporter;
+
+export { invalidCommit as $, bytesToHex as N, compareBytes as Q, compareEntryPath as U, comparePaths as V, computeHunks as X, consoleProgress as Y, detectRuntime as Z, hexToBytes as _, invalidDiffInput as a0, invalidFileMode as a1, invalidIdentity as a2, invalidIndexEntry as a3, invalidIndexHeader as a4, invalidObjectHeader as a5, invalidObjectId as a6, invalidTag as a7, invalidTreeEntry as a8, invalidTreeForDiff as a9, isBrowser as aa, isGitlink as ab, isNode as ac, isSameKind as ad, kindOf as ae, noopProgress as af, parseIndex as ag, payloadByteLength as ah, renderPatch as ai, serializeIndex as aj, sortByPath as ak, stripspace as al, TsgitError as v };
+export type { AdapterSet as A, BodyLine as B, WorkdirSnapshot as C, DiffError as D, EntryOf as E, WorkdirSnapshotOptions as F, GenerationView as G, WorkdirStat as H, IndexCachedStat as I, WriteEventEmitter as J, WriteEventStream as K, WriteScope as L, ModeKind as M, OuterJoinRow as O, PatchFile as P, ResolveOptions as R, Snapshot as S, TreeEntry as T, WalkIgnorePredicate as W, Disposable as a, DomainObjectError as b, IndexEntry as c, IndexEntryRow as d, IndexError as e, IndexFlags as f, IndexResolver as g, IndexSnapshot as h, InnerJoinRow as i, OutputHunk as j, PatchOptions as k, PatchPathPrefix as l, Pathspec as m, SnapshotEntry as n, SnapshotFactory as o, SnapshotKind as p, SnapshotOptions as q, StashSnapshot as r, TreeEntryRow as s, TreeResolver as t, TreeSnapshot as u, WorkdirEntry as w, WorkdirEntryRow as x, WorkdirEnumOptions as y, WorkdirEnumerator as z };