@foss.global/gitmanager 1.7.1 → 2.1.0

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/gitmanager',
-  version: '1.7.1',
+  version: '2.1.0',
   description: 'Headless Git manager for the foss.global Git platform, with a TypeScript API and Rust engine.'
 }

package/ts/classes.archiveinspection.ts

@@ -0,0 +1,245 @@
+import * as plugins from './plugins.js';
+import { GitManagerError } from './classes.gitmanagererror.js';
+import type {
+  IGitManagerArchiveInspection,
+  IGitManagerArchiveInspectionRequest,
+} from './models.js';
+
+/** The fixed ci-spec path-metadata ceiling of every archive. */
+export const gitManagerArchivePathMetadataCeilingBytes = 134_217_728;
+
+const maxInspectorOutputBytes = 64 * 1024;
+
+type TInspectorSettlement =
+  | { kind: 'closed'; code: number | null; signal: NodeJS.Signals | null }
+  | { kind: 'spawnFailed'; error: Error };
+
+const assertLimit = (
+  nameArg: string,
+  valueArg: number,
+  minimumArg: number,
+  maximumArg: number,
+): void => {
+  if (!Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError(
+      `${nameArg} must be a safe integer between ${minimumArg} and ${maximumArg}.`,
+    );
+  }
+};
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const isCount = (valueArg: unknown): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 0;
+
+/**
+ * Parses the inspector's single JSON result: the recomputed metadata of an
+ * accepted archive, or a thrown `GitManagerError` for a refused one.
+ */
+const parseInspectorResult = (stdoutArg: string): IGitManagerArchiveInspection => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdoutArg);
+  } catch (error) {
+    throw new Error('Archive inspector returned invalid JSON', { cause: error });
+  }
+  if (isRecord(parsed) && parsed.status === 'rejected' && typeof parsed.message === 'string') {
+    if (parsed.reason === 'limitExceeded') {
+      throw new GitManagerError('archiveLimitExceeded', parsed.message);
+    }
+    if (parsed.reason === 'invalid') {
+      throw new GitManagerError('archiveRejected', parsed.message);
+    }
+  }
+  if (
+    isRecord(parsed)
+    && parsed.status === 'accepted'
+    && isCount(parsed.sizeBytes)
+    && typeof parsed.sha256 === 'string'
+    && /^[0-9a-f]{64}$/.test(parsed.sha256)
+    && isCount(parsed.extractedSizeBytes)
+    && isCount(parsed.entryCount)
+    && isCount(parsed.pathMetadataBytes)
+  ) {
+    return {
+      sizeBytes: parsed.sizeBytes,
+      sha256: parsed.sha256,
+      extractedSizeBytes: parsed.extractedSizeBytes,
+      entryCount: parsed.entryCount,
+      pathMetadataBytes: parsed.pathMetadataBytes,
+    };
+  }
+  throw new Error('Archive inspector returned an invalid result');
+};
+
+/**
+ * Streams one archive into a dedicated engine inspector process and returns
+ * its recomputed metadata. The inspector reads until the archive is accepted
+ * or the first violation; on a refusal the remaining input is not read and
+ * the source is closed. Aborting `signalArg` kills the inspector and rejects
+ * with the abort reason once the process has exited.
+ */
+export const runArchiveInspection = async (
+  binaryPathArg: string,
+  requestArg: IGitManagerArchiveInspectionRequest,
+  signalArg: AbortSignal,
+): Promise<IGitManagerArchiveInspection> => {
+  const maxPathMetadataBytes =
+    requestArg.maxPathMetadataBytes ?? gitManagerArchivePathMetadataCeilingBytes;
+  assertLimit('maxCompressedBytes', requestArg.maxCompressedBytes, 0, Number.MAX_SAFE_INTEGER);
+  assertLimit('maxExtractedBytes', requestArg.maxExtractedBytes, 0, Number.MAX_SAFE_INTEGER);
+  assertLimit('maxEntries', requestArg.maxEntries, 0, Number.MAX_SAFE_INTEGER);
+  assertLimit(
+    'maxPathMetadataBytes',
+    maxPathMetadataBytes,
+    1,
+    gitManagerArchivePathMetadataCeilingBytes,
+  );
+  if (signalArg.aborted) {
+    throw signalArg.reason;
+  }
+
+  const child = plugins.childProcess.spawn(binaryPathArg, [
+    '--inspect-archive-stream',
+    '--max-compressed-bytes',
+    String(requestArg.maxCompressedBytes),
+    '--max-extracted-bytes',
+    String(requestArg.maxExtractedBytes),
+    '--max-entries',
+    String(requestArg.maxEntries),
+    '--max-path-metadata-bytes',
+    String(maxPathMetadataBytes),
+  ], { stdio: ['pipe', 'pipe', 'pipe'] });
+  const killInspector = (): void => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGKILL');
+    }
+  };
+
+  const settled = new Promise<TInspectorSettlement>((resolve) => {
+    child.once('error', (error) => {
+      killInspector();
+      resolve({ kind: 'spawnFailed', error });
+    });
+    child.once('close', (code, signal) => resolve({ kind: 'closed', code, signal }));
+  });
+  let inspectorSettled = false;
+  void settled.then(() => {
+    inspectorSettled = true;
+  });
+
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  let outputBytes = 0;
+  let outputOverflow = false;
+  const collect = (chunksArg: Buffer[]) => (chunkArg: Buffer): void => {
+    outputBytes += chunkArg.byteLength;
+    if (outputBytes > maxInspectorOutputBytes) {
+      outputOverflow = true;
+      killInspector();
+      return;
+    }
+    chunksArg.push(chunkArg);
+  };
+  child.stdout.on('data', collect(stdoutChunks));
+  child.stderr.on('data', collect(stderrChunks));
+
+  // A write error is the inspector closing its input after a refusal (or
+  // dying); its exit status and result decide the outcome.
+  child.stdin.on('error', () => undefined);
+
+  let aborted = false;
+  const abortInspection = (): void => {
+    aborted = true;
+    killInspector();
+  };
+  signalArg.addEventListener('abort', abortInspection, { once: true });
+
+  let delivered = false;
+  let sourceFailure: { error: unknown } | undefined;
+  const waitForDrain = (): Promise<unknown> => Promise.race([
+    new Promise<void>((resolve) => {
+      const done = (): void => {
+        child.stdin.off('drain', done);
+        child.stdin.off('close', done);
+        resolve();
+      };
+      child.stdin.once('drain', done);
+      child.stdin.once('close', done);
+    }),
+    settled,
+  ]);
+  const feed = async (): Promise<void> => {
+    const archive = requestArg.archive;
+    if (archive instanceof Uint8Array) {
+      child.stdin.end(archive);
+      delivered = true;
+      return;
+    }
+    const iterator = archive[Symbol.asyncIterator]();
+    let exhausted = false;
+    try {
+      while (!inspectorSettled) {
+        const step = await Promise.race([
+          iterator.next().then((result) => ({ kind: 'chunk' as const, result })),
+          settled.then(() => ({ kind: 'settled' as const })),
+        ]);
+        if (step.kind === 'settled' || inspectorSettled) {
+          return;
+        }
+        if (step.result.done) {
+          exhausted = true;
+          child.stdin.end();
+          delivered = true;
+          return;
+        }
+        if (!(step.result.value instanceof Uint8Array)) {
+          throw new TypeError('The archive stream must yield Uint8Array chunks.');
+        }
+        if (!child.stdin.write(step.result.value)) {
+          await waitForDrain();
+        }
+      }
+    } catch (error) {
+      sourceFailure = { error };
+      killInspector();
+    } finally {
+      if (!exhausted && !sourceFailure) {
+        // Close the source like a `for await` loop that stops early; a
+        // stalled source must not hold the inspection open.
+        void Promise.resolve(iterator.return?.()).catch(() => undefined);
+      }
+    }
+  };
+
+  try {
+    const [settlement] = await Promise.all([settled, feed()]);
+    if (aborted) {
+      throw signalArg.reason;
+    }
+    if (sourceFailure) {
+      throw sourceFailure.error;
+    }
+    if (settlement.kind === 'spawnFailed') {
+      throw new Error('Failed to spawn the archive inspector', { cause: settlement.error });
+    }
+    if (outputOverflow) {
+      throw new Error('Archive inspector output exceeded its limit');
+    }
+    if (settlement.code !== 0) {
+      const stderr = Buffer.concat(stderrChunks).toString('utf8').trim();
+      throw new Error(
+        `Archive inspector failed with ${settlement.signal ?? `status ${settlement.code}`}`
+          + (stderr ? `: ${stderr}` : ''),
+      );
+    }
+    const inspection = parseInspectorResult(Buffer.concat(stdoutChunks).toString('utf8'));
+    if (!delivered) {
+      throw new Error('Archive inspector accepted an archive that was not completely delivered');
+    }
+    return inspection;
+  } finally {
+    signalArg.removeEventListener('abort', abortInspection);
+  }
+};

package/ts/classes.gitmanager.ts

@@ -1,5 +1,9 @@
 import * as plugins from './plugins.js';
 import type {
+  IGitManagerAncestryRequest,
+  IGitManagerArchiveInspection,
+  IGitManagerArchiveInspectionOptions,
+  IGitManagerArchiveInspectionRequest,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -13,7 +17,6 @@ import type {
   IGitManagerMergeRequest,
   IGitManagerMergeResult,
   IGitManagerReadFileRequest,
-  IGitManagerRef,
   IGitManagerRefRequest,
   IGitManagerProtectedRefsApplyResult,
   IGitManagerSmartHttpRepositoryProtectedRefs,
@@ -37,10 +40,12 @@ import type {
   IGitManagerReadinessOptions,
   IRustGitManagerConfig,
   TGitManagerReadinessFailureReason,
+  TGitManagerRefInventoryResult,
   TGitManagerReadinessResult,
 } from './models.js';
 import { RustGitManagerBridge } from './rust-gitmanager-bridge.js';
 import { GitManagerRepositoryService } from './classes.repositoryservice.js';
+import { runArchiveInspection } from './classes.archiveinspection.js';
 
 const readinessDefaultTimeoutMs = 2_000;
 const readinessMaximumTimeoutMs = 30_000;
@@ -56,6 +61,7 @@ export class GitManager extends plugins.EventEmitter {
   private stopPromise: Promise<void> | null = null;
   private config: IRustGitManagerConfig;
   private readonly repositoryServices = new Set<GitManagerRepositoryService>();
+  private readonly archiveInspections = new Map<AbortController, Promise<unknown>>();
   private lifecycleEpoch = 0;
   private smartHttpProbeUrl: string | null = null;
   private readonly activeReadinessControllers = new Set<AbortController>();
@@ -168,12 +174,14 @@ export class GitManager extends plugins.EventEmitter {
     }
     if (!this.bridge.running) {
       await this.closeRepositoryServices();
+      await this.abortArchiveInspections();
       await this.bridge.terminate();
       this.started = false;
       return;
     }
     try {
       await this.closeRepositoryServices();
+      await this.abortArchiveInspections();
       await this.bridge.stopGitManager();
     } finally {
       await this.bridge.terminate();
@@ -403,7 +411,15 @@ export class GitManager extends plugins.EventEmitter {
     return this.bridge.listRepositories();
   }
 
-  public async listRefs(requestArg: IGitManagerRefRequest): Promise<IGitManagerRef[]> {
+  /**
+   * Lists one page of the repository's complete ref inventory. Without
+   * `prefixes` every ref under `refs/` is selected; follow
+   * `pagination.cursor` until `exhausted`, and restart without a cursor on a
+   * `stale` result.
+   */
+  public async listRefs(
+    requestArg: IGitManagerRefRequest,
+  ): Promise<TGitManagerRefInventoryResult> {
     this.assertRunning();
     return this.bridge.listRefs(requestArg);
   }
@@ -432,6 +448,51 @@ export class GitManager extends plugins.EventEmitter {
     return this.bridge.readFile(requestArg);
   }
 
+  /**
+   * Answers `git merge-base --is-ancestor` exactly within a work budget.
+   * Anything short of an exact answer throws a `GitManagerError`
+   * (`invalidObjectId`, `objectNotFound`, `objectNotCommit`,
+   * `ancestryBudgetExceeded`); it never degrades to `false`.
+   */
+  public async isAncestor(requestArg: IGitManagerAncestryRequest): Promise<boolean> {
+    this.assertRunning();
+    return this.bridge.isAncestor(requestArg);
+  }
+
+  /**
+   * Inspects a receiver-side `tar.gz` archive in a dedicated engine process:
+   * recomputes its compressed size, SHA-256, extracted bytes, entry count,
+   * and path metadata bytes while enforcing the limits and the ci-spec path
+   * and link rules. A refused archive throws a `GitManagerError` with code
+   * `archiveLimitExceeded` or `archiveRejected`; an invalid limit throws a
+   * `TypeError`. `stop()` aborts inspections in flight.
+   */
+  public async inspectArchive(
+    requestArg: IGitManagerArchiveInspectionRequest,
+    optionsArg: IGitManagerArchiveInspectionOptions = {},
+  ): Promise<IGitManagerArchiveInspection> {
+    this.assertRunning();
+    const controller = new AbortController();
+    const callerSignal = optionsArg.signal;
+    const abortForCaller = (): void => {
+      controller.abort(callerSignal?.reason);
+    };
+    if (callerSignal?.aborted) {
+      throw callerSignal.reason;
+    }
+    callerSignal?.addEventListener('abort', abortForCaller, { once: true });
+    const inspection = this.bridge.findBinary().then((binaryPath) => {
+      return runArchiveInspection(binaryPath, requestArg, controller.signal);
+    });
+    this.archiveInspections.set(controller, inspection);
+    try {
+      return await inspection;
+    } finally {
+      callerSignal?.removeEventListener('abort', abortForCaller);
+      this.archiveInspections.delete(controller);
+    }
+  }
+
   public async listCommits(requestArg: IGitManagerListCommitsRequest): Promise<IGitManagerCommitSummary[]> {
     this.assertRunning();
     return this.bridge.listCommits(requestArg);
@@ -667,6 +728,15 @@ export class GitManager extends plugins.EventEmitter {
     }
   }
 
+  private async abortArchiveInspections(): Promise<void> {
+    const inspections = [...this.archiveInspections];
+    this.archiveInspections.clear();
+    for (const [controller] of inspections) {
+      controller.abort(new Error('GitManager stopped during archive inspection'));
+    }
+    await Promise.all(inspections.map(([, inspection]) => inspection.catch(() => undefined)));
+  }
+
   private async closeRepositoryServices(): Promise<void> {
     const services = [...this.repositoryServices];
     this.repositoryServices.clear();

package/ts/classes.gitmanagererror.ts

@@ -0,0 +1,28 @@
+import type { TGitManagerErrorCode } from './models.js';
+
+const gitManagerErrorCodes: ReadonlySet<string> = new Set<TGitManagerErrorCode>([
+  'invalidObjectId',
+  'objectNotFound',
+  'objectNotCommit',
+  'ancestryBudgetExceeded',
+  'archiveLimitExceeded',
+  'archiveRejected',
+]);
+
+export const isGitManagerErrorCode = (valueArg: unknown): valueArg is TGitManagerErrorCode =>
+  typeof valueArg === 'string' && gitManagerErrorCodes.has(valueArg);
+
+/**
+ * A failure callers can branch on through its stable `code`. Other failures,
+ * such as an unknown repository or an engine that is not running, remain
+ * plain errors.
+ */
+export class GitManagerError extends Error {
+  public readonly code: TGitManagerErrorCode;
+
+  constructor(codeArg: TGitManagerErrorCode, messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'GitManagerError';
+    this.code = codeArg;
+  }
+}

package/ts/classes.repositoryservice.ts

@@ -3,6 +3,7 @@ import type {
   IGitManagerRepositoryServiceRequest,
   IGitManagerRepositoryServiceResult,
   IRustGitManagerRepositoryServiceDescriptor,
+  TGitManagerRepositoryServiceFailure,
 } from './models.js';
 
 class ByteLimitTransform extends plugins.stream.Transform {
@@ -11,7 +12,7 @@ class ByteLimitTransform extends plugins.stream.Transform {
   constructor(
     private readonly maximumBytes: number,
     private readonly label: string,
-    private readonly onLimit: (errorArg: Error) => void,
+    private readonly onLimit: () => void,
   ) {
     super();
   }
@@ -28,9 +29,8 @@ class ByteLimitTransform extends plugins.stream.Transform {
         : Buffer.from(chunkArg);
     this.bytes += chunk.byteLength;
     if (!Number.isSafeInteger(this.bytes) || this.bytes > this.maximumBytes) {
-      const error = new Error(this.label + ' exceeded the configured size limit');
-      this.onLimit(error);
-      callbackArg(error);
+      this.onLimit();
+      callbackArg(new Error(this.label + ' exceeded the configured size limit'));
       return;
     }
     callbackArg(null, chunk);
@@ -82,6 +82,7 @@ export class GitManagerRepositoryService {
   public readonly completed: Promise<IGitManagerRepositoryServiceResult>;
   private readonly child: plugins.childProcess.ChildProcessWithoutNullStreams;
   private completionSettled = false;
+  private failure: TGitManagerRepositoryServiceFailure | null = null;
   private timeout?: NodeJS.Timeout;
 
   constructor(
@@ -134,25 +135,31 @@ export class GitManagerRepositoryService {
       stdio: ['pipe', 'pipe', 'pipe'],
       windowsHide: true,
     });
-    const fail = (errorArg: Error) => {
-      this.terminate();
-      return errorArg;
-    };
+    const failWith = (failureArg: TGitManagerRepositoryServiceFailure) =>
+      () => this.fail(failureArg);
     const input = new ByteLimitTransform(
       descriptorArg.maxRequestBytes,
       'Git repository service request',
-      fail,
+      failWith('requestLimitExceeded'),
     );
     const output = new ByteLimitTransform(
       descriptorArg.maxResponseBytes,
       'Git repository service response',
-      fail,
+      failWith('responseLimitExceeded'),
     );
     const stderr = new ByteLimitTransform(
       128 * 1024,
       'Git repository service stderr',
-      fail,
+      failWith('stderrLimitExceeded'),
     );
+    // The service owns every stream error: a consumer's pipe() into stdin
+    // would otherwise rethrow an unhandled error. Failures surface through
+    // `completed`. Git closing its stdin early is reported by its exit
+    // status, so write errors on the child's stdin end only the pipe.
+    for (const ownedStream of [input, output, stderr, this.child.stdout, this.child.stderr]) {
+      ownedStream.on('error', failWith('streamFailed'));
+    }
+    this.child.stdin.on('error', () => undefined);
     input.pipe(this.child.stdin);
     this.child.stdout.pipe(output);
     this.child.stderr.pipe(stderr);
@@ -173,11 +180,12 @@ export class GitManagerRepositoryService {
         resolve({
           exitCode,
           signal: signal as NodeJS.Signals | null,
+          failure: this.failure,
         });
       });
     });
     this.timeout = setTimeout(() => {
-      this.terminate();
+      this.fail('processTimeout');
     }, descriptorArg.processTimeoutMs);
     this.timeout.unref();
   }
@@ -198,12 +206,33 @@ export class GitManagerRepositoryService {
     this.child.kill('SIGKILL');
   }
 
+  /**
+   * Kills the Git process tree and releases every stream, including output
+   * the caller never read, so `completed` settles without depending on the
+   * caller draining it.
+   */
   public async close(): Promise<void> {
     this.stdin.destroy();
     this.terminate();
+    for (const ownedStream of [
+      this.stdout,
+      this.stderr,
+      this.child.stdout,
+      this.child.stderr,
+    ]) {
+      ownedStream.destroy();
+    }
     await this.completed.catch(() => undefined);
   }
 
+  /** Records the first failure and terminates the Git process tree. */
+  private fail(failureArg: TGitManagerRepositoryServiceFailure): void {
+    if (!this.failure && !this.completionSettled) {
+      this.failure = failureArg;
+    }
+    this.terminate();
+  }
+
   private clearTimeout(): void {
     if (this.timeout) {
       clearTimeout(this.timeout);

package/ts/index.ts

@@ -2,3 +2,5 @@ export * from './models.js';
 export * from './rust-gitmanager-bridge.js';
 export * from './classes.gitmanager.js';
 export * from './classes.repositoryservice.js';
+export * from './classes.gitmanagererror.js';
+export { gitManagerArchivePathMetadataCeilingBytes } from './classes.archiveinspection.js';

package/ts/models.ts

@@ -89,6 +89,71 @@ export interface IGitManagerRepositoryArchive
   entryCount: number;
 }
 
+/**
+ * Asks whether `ancestorObjectId` is reachable from `descendantObjectId`
+ * (`git merge-base --is-ancestor`; a commit is its own ancestor). Both must be
+ * full lowercase object IDs of commits in the repository; revision
+ * expressions, abbreviations, and tag objects are refused.
+ */
+export interface IGitManagerAncestryRequest extends IGitManagerRepositorySelector {
+  ancestorObjectId: string;
+  descendantObjectId: string;
+  /**
+   * Wall-clock work budget for the object lookup and the history walk,
+   * 1 to 60000 ms, default 10000. Exceeding it throws a `GitManagerError`
+   * with code `ancestryBudgetExceeded`.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Limits for inspecting one `tar.gz` archive. Every limit is inclusive.
+ */
+export interface IGitManagerArchiveInspectionRequest {
+  /** The archive bytes, or a stream of them; it is consumed and closed. */
+  archive: Uint8Array | AsyncIterable<Uint8Array>;
+  maxCompressedBytes: number;
+  maxExtractedBytes: number;
+  maxEntries: number;
+  /**
+   * Ceiling for the UTF-8 bytes of every effective entry path and symlink
+   * target, 1 to 134217728 (the fixed ci-spec ceiling, and the default).
+   */
+  maxPathMetadataBytes?: number;
+}
+
+export interface IGitManagerArchiveInspectionOptions {
+  signal?: AbortSignal;
+}
+
+/** Metadata recomputed from an accepted archive; nothing is taken on trust. */
+export interface IGitManagerArchiveInspection {
+  sizeBytes: number;
+  sha256: string;
+  extractedSizeBytes: number;
+  entryCount: number;
+  pathMetadataBytes: number;
+}
+
+/**
+ * Stable codes of `GitManagerError`.
+ *
+ * - `invalidObjectId`: an object ID is not a full lowercase SHA-1 or SHA-256.
+ * - `objectNotFound`: the object does not exist in the repository.
+ * - `objectNotCommit`: the object exists but is not a commit.
+ * - `ancestryBudgetExceeded`: the ancestry check exceeded `timeoutMs`; the
+ *   answer is unknown, never `false`.
+ * - `archiveLimitExceeded`: the archive exceeds a requested limit.
+ * - `archiveRejected`: the archive breaks a format, path, or link rule.
+ */
+export type TGitManagerErrorCode =
+  | 'invalidObjectId'
+  | 'objectNotFound'
+  | 'objectNotCommit'
+  | 'ancestryBudgetExceeded'
+  | 'archiveLimitExceeded'
+  | 'archiveRejected';
+
 export interface IGitManagerRepositoryLfsPointer {
   oid: string;
   sizeBytes: number;
@@ -115,9 +180,26 @@ export interface IRustGitManagerRepositoryServiceDescriptor
   idleTimeoutSeconds: number;
 }
 
+/**
+ * Why GitManager terminated a repository service process. The value says the
+ * transfer was cut, not that the repository is unchanged: an SSH-style
+ * receive-pack has no receive gate, so Git updates refs as soon as it has read
+ * a complete pack, and excess bytes arriving after that cannot undo those
+ * updates. Reconcile refs from the repository after every receive-pack,
+ * whatever `failure` says.
+ */
+export type TGitManagerRepositoryServiceFailure =
+  | 'requestLimitExceeded'
+  | 'responseLimitExceeded'
+  | 'stderrLimitExceeded'
+  | 'streamFailed'
+  | 'processTimeout';
+
 export interface IGitManagerRepositoryServiceResult {
   exitCode: number | null;
   signal: NodeJS.Signals | null;
+  /** The first failure that made GitManager terminate the process; null otherwise. */
+  failure: TGitManagerRepositoryServiceFailure | null;
 }
 
 export interface IGitManagerRestoreBundleRequest
@@ -231,6 +313,9 @@ export type {
   IGitManagerMergeResult,
   IGitManagerReadFileRequest,
   IGitManagerRef,
+  IGitManagerRefHead,
+  IGitManagerRefInventoryPage,
+  IGitManagerRefInventoryStale,
   IGitManagerRefRequest,
   IGitManagerRepositoryInfo,
   IGitManagerRepositorySelector,
@@ -243,6 +328,7 @@ export type {
   TGitManagerMergeMethod,
   TGitManagerMergeStatus,
   TGitManagerObjectType,
-  TGitManagerRefType,
+  TGitManagerRefInventoryPagination,
+  TGitManagerRefInventoryResult,
   TGitManagerTreeEntryType,
 } from '@foss.global/interfaces';