@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/git-steps.md

@@ -0,0 +1,1010 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / git-steps
+
+# git-steps
+
+## Classes
+
+### GitStepMaterialError
+
+Permanent continuation failure: background owners settle their lane instead of
+retrying it.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new GitStepMaterialError(code): GitStepMaterialError;
+```
+
+Construct the canonical permanent continuation error.
+
+###### Parameters
+
+| Parameter | Type                                                                                                    | Description                            |
+| --------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `code`    | \| `"unavailable"` \| `"conflict"` \| `"digest_mismatch"` \| `"atomic_unavailable"` \| `"push_refused"` | Permanent continuation failure reason. |
+
+###### Returns
+
+[`GitStepMaterialError`](#gitstepmaterialerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code:
+  | "unavailable"
+  | "conflict"
+  | "digest_mismatch"
+  | "atomic_unavailable"
+  | "push_refused";
+```
+
+Invalid material, unavailable atomic support, or an exhausted unchanged-head
+push refusal.
+
+## Type Aliases
+
+### GitStepMaterial
+
+```ts
+type GitStepMaterial = Readonly<{
+  put: Promise<void>;
+  read: Promise<Uint8Array<ArrayBufferLike>>;
+  drop: Promise<void>;
+}>;
+```
+
+Facet-owned immutable material, split into individually bounded rows.
+
+---
+
+### GitStepSql
+
+```ts
+type GitStepSql = Readonly<{
+  exec: {
+    toArray: readonly Readonly<
+      Record<string, string | number | ArrayBuffer | null>
+    >[];
+  };
+}>;
+```
+
+Existing facet SQLite owner; no transaction or scheduler is introduced here.
+
+---
+
+### GitStep
+
+```ts
+type GitStep = z.output<typeof gitStepSchema>;
+```
+
+Durable checkpoint, suitable for a Watchdog payload and fresh-frame
+re-admission.
+
+---
+
+### GitStepOperation
+
+```ts
+type GitStepOperation =
+  | Readonly<{
+      kind: "commit";
+      requestKey: string;
+      request: CommitFilesRequest;
+      tags?: readonly Readonly<{
+        ref: string;
+        expected: string | null;
+      }>[];
+      timestamp?: number;
+    }>
+  | Readonly<{
+      kind: "merge";
+      requestKey: string;
+      request: MergeBranchRequest;
+      timestamp?: number;
+    }>;
+```
+
+Caller-owned operation; begin fixes the timestamp and stores file bytes outside
+the checkpoint.
+
+---
+
+### GitStepOutcome
+
+```ts
+type GitStepOutcome =
+  | GitWriteOutcome
+  | GitMergeOutcome
+  | Readonly<{
+      kind: "too_large";
+    }>;
+```
+
+Final Git outcome; oversize material refuses before any receive-pack.
+
+---
+
+### GitStepResult
+
+```ts
+type GitStepResult =
+  | Readonly<{
+      next: GitStep;
+    }>
+  | Readonly<{
+      done: GitStepOutcome;
+    }>
+  | Readonly<{
+      yield: true;
+    }>;
+```
+
+One step either checkpoints, settles, or yields before transport.
+
+---
+
+### GitStepPorts
+
+```ts
+type GitStepPorts = Readonly<{
+  git: GitCommitStore;
+  material: GitStepMaterial;
+}>;
+```
+
+Per-frame transport plus the existing facet's durable material owner.
+
+## Variables
+
+### gitStepSchema
+
+```ts
+const gitStepSchema: ZodDiscriminatedUnion<[ZodObject<{
+  key: ZodString;
+  timestamp: ZodNumber;
+  operation: ZodDiscriminatedUnion<[ZodObject<{
+     kind: ZodLiteral<"commit">;
+     request: ZodObject<{
+        repository: ZodString;
+        branch: ZodString;
+        expectedHead: ZodNullable<...>;
+        startFrom: ZodOptional<...>;
+        message: ZodString;
+        author: ZodObject<..., ...>;
+     }, $strict>;
+     changesDigest: ZodCustomStringFormat<"sha256_hex">;
+     tags: ZodArray<ZodObject<{
+        ref: ...;
+        expected: ...;
+     }, $strict>>;
+   }, $strict>, ZodObject<{
+     kind: ZodLiteral<"merge">;
+     request: ZodObject<{
+        target: ZodString;
+        source: ZodString;
+        branch: ZodString;
+        sourceBranch: ZodString;
+        expectedSource: ZodString;
+        expectedTarget: ZodOptional<...>;
+        behind: ZodOptional<...>;
+        message: ZodString;
+        author: ZodObject<..., ...>;
+     }, $strict>;
+  }, $strict>], "kind">;
+  phase: ZodLiteral<"fetch-base">;
+  base: ZodNullable<ZodString>;
+}, $strict>, ZodObject<{
+  key: ZodString;
+  timestamp: ZodNumber;
+  operation: ZodDiscriminatedUnion<[ZodObject<{
+     kind: ZodLiteral<"commit">;
+     request: ZodObject<{
+        repository: ZodString;
+        branch: ZodString;
+        expectedHead: ZodNullable<...>;
+        startFrom: ZodOptional<...>;
+        message: ZodString;
+        author: ZodObject<..., ...>;
+     }, $strict>;
+     changesDigest: ZodCustomStringFormat<"sha256_hex">;
+     tags: ZodArray<ZodObject<{
+        ref: ...;
+        expected: ...;
+     }, $strict>>;
+   }, $strict>, ZodObject<{
+     kind: ZodLiteral<"merge">;
+     request: ZodObject<{
+        target: ZodString;
+        source: ZodString;
+        branch: ZodString;
+        sourceBranch: ZodString;
+        expectedSource: ZodString;
+        expectedTarget: ZodOptional<...>;
+        behind: ZodOptional<...>;
+        message: ZodString;
+        author: ZodObject<..., ...>;
+     }, $strict>;
+  }, $strict>], "kind">;
+  phase: ZodLiteral<"too-large">;
+}, $strict>, ZodObject<{
+  key: ZodString;
+  timestamp: ZodNumber;
+  operation: ZodDiscriminatedUnion<[ZodObject<{
+     kind: ZodLiteral<"commit">;
+     request: ZodObject<{
+        repository: ZodString;
+        branch: ZodString;
+        expectedHead: ZodNullable<...>;
+        startFrom: ZodOptional<...>;
+        message: ZodString;
+        author: ZodObject<..., ...>;
+     }, $strict>;
+     changesDigest: ZodCustomStringFormat<"sha256_hex">;
+     tags: ZodArray<ZodObject<{
+        ref: ...;
+        expected: ...;
+     }, $strict>>;
+   }, $strict>, ZodObject<{
+     kind: ZodLiteral<"merge">;
+     request: ZodObject<{
+        target: ZodString;
+        source: ZodString;
+        branch: ZodString;
+        sourceBranch: ZodString;
+        expectedSource: ZodString;
+        expectedTarget: ZodOptional<...>;
+        behind: ZodOptional<...>;
+        message: ZodString;
+        author: ZodObject<..., ...>;
+     }, $strict>;
+  }, $strict>], "kind">;
+  phase: ZodLiteral<"inspect-base">;
+}, $strict>], "phase">;
+```
+
+Strict, JSON-only continuation grammar; material and authority are not stored in
+it.
+
+## Functions
+
+### sqliteGitStepMaterial()
+
+```ts
+function sqliteGitStepMaterial(sql): GitStepMaterial;
+```
+
+One-MiB material rows; exact replays are idempotent, conflicting material
+refuses.
+
+#### Parameters
+
+| Parameter | Type                        |
+| --------- | --------------------------- |
+| `sql`     | [`GitStepSql`](#gitstepsql) |
+
+#### Returns
+
+[`GitStepMaterial`](#gitstepmaterial)
+
+---
+
+### memoryGitStepMaterial()
+
+```ts
+function memoryGitStepMaterial(): GitStepMaterial;
+```
+
+Volatile foreground driver material; background callers use the facet owner.
+
+#### Returns
+
+[`GitStepMaterial`](#gitstepmaterial)
+
+---
+
+### begin()
+
+```ts
+function begin(
+  input,
+  material,
+): Promise<
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "fetch-base";
+      base: string | null;
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "too-large";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "inspect-base";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "inspect-source";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "fetch-source";
+      target?: string;
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "inspect-target";
+      sourceDigest: string;
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      phase: "fetch-target";
+      sourceDigest: string;
+      target: string;
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      old: string | null;
+      built: string;
+      packDigest: string;
+      attempt: number;
+      pushBefore?: string | null;
+      atomic?: true;
+      phase: "inspect-merge-push";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      old: string | null;
+      built: string;
+      packDigest: string;
+      attempt: number;
+      pushBefore?: string | null;
+      atomic?: true;
+      phase: "inspect-atomic";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      old: string | null;
+      built: string;
+      packDigest: string;
+      attempt: number;
+      pushBefore?: string | null;
+      atomic?: true;
+      phase: "push";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      old: string | null;
+      built: string;
+      packDigest: string;
+      attempt: number;
+      pushBefore?: string | null;
+      atomic?: true;
+      phase: "confirm";
+    }
+  | {
+      key: string;
+      timestamp: number;
+      operation:
+        | {
+            kind: "commit";
+            request: {
+              repository: string;
+              branch: string;
+              expectedHead: string | null;
+              startFrom?: string;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+            changesDigest: string;
+            tags: object[];
+          }
+        | {
+            kind: "merge";
+            request: {
+              target: string;
+              source: string;
+              branch: string;
+              sourceBranch: string;
+              expectedSource: string;
+              expectedTarget?: string;
+              behind?: number;
+              message: string;
+              author: {
+                name: string;
+                email: string;
+              };
+            };
+          };
+      old: string | null;
+      built: string;
+      packDigest: string;
+      attempt: number;
+      pushBefore?: string | null;
+      atomic?: true;
+      phase: "confirm-ancestry";
+      head: string;
+    }
+>;
+```
+
+Prepare immutable request material before atomically enqueueing the first
+checkpoint.
+
+#### Parameters
+
+| Parameter  | Type                                    |
+| ---------- | --------------------------------------- |
+| `input`    | [`GitStepOperation`](#gitstepoperation) |
+| `material` | [`GitStepMaterial`](#gitstepmaterial)   |
+
+#### Returns
+
+`Promise`\< \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{
+`kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`;
+`expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`;
+`author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`:
+`string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{
+`target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`:
+`string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`:
+`number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`;
+\}; \}; \}; `phase`: `"fetch-base"`; `base`: `string` \| `null`; \} \| \{ `key`:
+`string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`;
+`request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`:
+`string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{
+`name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`:
+`object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`;
+`source`: `string`; `branch`: `string`; `sourceBranch`: `string`;
+`expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+\}; `phase`: `"too-large"`; \} \| \{ `key`: `string`; `timestamp`: `number`;
+`operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`;
+`branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+`changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`;
+`request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`;
+`sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`:
+`string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`:
+`string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-base"`; \} \| \{
+`key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`;
+`request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`:
+`string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{
+`name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`:
+`object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`;
+`source`: `string`; `branch`: `string`; `sourceBranch`: `string`;
+`expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+\}; `phase`: `"inspect-source"`; \} \| \{ `key`: `string`; `timestamp`:
+`number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`:
+`string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`:
+`string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`;
+\}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`:
+`"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`:
+`string`; `sourceBranch`: `string`; `expectedSource`: `string`;
+`expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`:
+\{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-source"`;
+`target?`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`;
+`operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`;
+`branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+`changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`;
+`request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`;
+`sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`:
+`string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`:
+`string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-target"`;
+`sourceDigest`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`;
+`operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`;
+`branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+`changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`;
+`request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`;
+`sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`:
+`string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`:
+`string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-target"`;
+`sourceDigest`: `string`; `target`: `string`; \} \| \{ `key`: `string`;
+`timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{
+`repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`;
+`startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`;
+`email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \|
+\{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`;
+`branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`;
+`expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`:
+\{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`;
+`built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`:
+`string` \| `null`; `atomic?`: `true`; `phase`: `"inspect-merge-push"`; \} \| \{
+`key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`;
+`request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`:
+`string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{
+`name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`:
+`object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`;
+`source`: `string`; `branch`: `string`; `sourceBranch`: `string`;
+`expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+\}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`;
+`attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`;
+`phase`: `"inspect-atomic"`; \} \| \{ `key`: `string`; `timestamp`: `number`;
+`operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`;
+`branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+`changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`;
+`request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`;
+`sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`:
+`string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`:
+`string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`:
+`string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string`
+\| `null`; `atomic?`: `true`; `phase`: `"push"`; \} \| \{ `key`: `string`;
+`timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{
+`repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`;
+`startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`;
+`email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \|
+\{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`;
+`branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`;
+`expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`:
+\{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`;
+`built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`:
+`string` \| `null`; `atomic?`: `true`; `phase`: `"confirm"`; \} \| \{ `key`:
+`string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`;
+`request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`:
+`string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{
+`name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`:
+`object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`;
+`source`: `string`; `branch`: `string`; `sourceBranch`: `string`;
+`expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`;
+`message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \};
+\}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`;
+`attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`;
+`phase`: `"confirm-ancestry"`; `head`: `string`; \}\>
+
+---
+
+### runStep()
+
+```ts
+function runStep(raw, ports, signal): Promise<GitStepResult>;
+```
+
+Execute one fresh-admitted frame; the caller persists next and its successor job
+atomically.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `raw`     | \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-base"`; `base`: `string` \| `null`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"too-large"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-base"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-source"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-source"`; `target?`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-target"`; `sourceDigest`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-target"`; `sourceDigest`: `string`; `target`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"inspect-merge-push"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"inspect-atomic"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"push"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"confirm"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"confirm-ancestry"`; `head`: `string`; \} |
+| `ports`   | [`GitStepPorts`](#gitstepports)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `signal`  | `AbortSignal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+
+#### Returns
+
+`Promise`\<[`GitStepResult`](#gitstepresult)\>
+
+---
+
+### dropMaterial()
+
+```ts
+function dropMaterial(step, material): Promise<void>;
+```
+
+Drop material only after the owner has durably recorded the terminal outcome.
+
+#### Parameters
+
+| Parameter  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `step`     | \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-base"`; `base`: `string` \| `null`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"too-large"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-base"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-source"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-source"`; `target?`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"inspect-target"`; `sourceDigest`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `phase`: `"fetch-target"`; `sourceDigest`: `string`; `target`: `string`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"inspect-merge-push"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"inspect-atomic"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"push"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"confirm"`; \} \| \{ `key`: `string`; `timestamp`: `number`; `operation`: \| \{ `kind`: `"commit"`; `request`: \{ `repository`: `string`; `branch`: `string`; `expectedHead`: `string` \| `null`; `startFrom?`: `string`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; `changesDigest`: `string`; `tags`: `object`[]; \} \| \{ `kind`: `"merge"`; `request`: \{ `target`: `string`; `source`: `string`; `branch`: `string`; `sourceBranch`: `string`; `expectedSource`: `string`; `expectedTarget?`: `string`; `behind?`: `number`; `message`: `string`; `author`: \{ `name`: `string`; `email`: `string`; \}; \}; \}; `old`: `string` \| `null`; `built`: `string`; `packDigest`: `string`; `attempt`: `number`; `pushBefore?`: `string` \| `null`; `atomic?`: `true`; `phase`: `"confirm-ancestry"`; `head`: `string`; \} |
+| `material` | [`GitStepMaterial`](#gitstepmaterial)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+#### Returns
+
+`Promise`\<`void`\>