> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> TypeScript SDK - Snapshot API reference

Capture the disk state of a stopped sandbox into a portable artifact, then boot fresh sandboxes from it. See [Snapshots](/sandboxes/snapshots) for concepts and walkthroughs.

```typescript theme={null}
import { Sandbox, Snapshot, SnapshotHandle } from "microsandbox";
import type { ExportOpts, SnapshotVerifyReport } from "microsandbox";
```

<Note>
  Snapshots are **disk-only** and require a sandbox that is not running (stopped or crashed).
</Note>

<p className="msb-label" id="typical-flow">Typical flow</p>

```typescript theme={null}
import { Sandbox, Snapshot } from "microsandbox";

// 1. capture: stop the sandbox, then snapshot its disk
const sb = await Sandbox.get("baseline");
await sb.stop();
const snap = await Snapshot.builder("baseline")
  .name("after-pip-install")     // bare name in the default dir
  .recordIntegrity()             // hash the upper layer
  .create();

// 2. boot a fresh sandbox from the snapshot
const fresh = await Sandbox.builder("worker")
  .fromSnapshot(snap.path)
  .create();
```

## Capture and boot

These entry points live on `SandboxBuilder` and `SandboxHandle`; they are the bridge between sandboxes and snapshot artifacts.

#### <span className="msb-recv">.</span><span className="msb-hn">fromSnapshot()</span>

```typescript theme={null}
fromSnapshot(pathOrName: string): SandboxBuilder
```

<Accordion title="Example">
  ```typescript theme={null}
  const sb = await Sandbox.builder("worker")
    .fromSnapshot("after-pip-install")
    .create();
  ```
</Accordion>

Boot a fresh sandbox from a snapshot artifact. Mutually exclusive with [`.image()`](/sdk/typescript/sandbox#image) — the snapshot already pins the image. Documented in full on the [Sandbox](/sdk/typescript/sandbox#fromsnapshot) page.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare name (resolved under the default snapshots directory) or filesystem path to an artifact directory.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="/sdk/typescript/sandbox#sandboxbuilder">SandboxBuilder</a></div>
    <div className="msb-param-desc">The same builder, for chaining.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">snapshot()</span>

```typescript theme={null}
snapshot(name: string): Promise<Snapshot>
```

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Sandbox.get("baseline");
  await h.stop();
  const snap = await h.snapshot("after-pip-install");
  ```
</Accordion>

Snapshot this sandbox under a bare name in the default snapshots directory (`~/.microsandbox/snapshots/<name>/`). Called on a [`SandboxHandle`](/sdk/typescript/sandbox#sandboxhandle). The sandbox must be stopped or crashed; running sandboxes are rejected with a `SnapshotSandboxRunning` error. For an explicit filesystem destination, see [`snapshotTo()`](#handle-snapshotto).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare name; becomes the artifact directory under the default snapshots dir.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot-instance">Promise\<Snapshot></a></div>
    <div className="msb-param-desc">The created snapshot artifact.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">snapshotTo()</span>

```typescript theme={null}
snapshotTo(path: string): Promise<Snapshot>
```

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await h.snapshotTo("/data/snapshots/baseline-v2");
  ```
</Accordion>

Snapshot this sandbox to an explicit filesystem path. Called on a [`SandboxHandle`](/sdk/typescript/sandbox#sandboxhandle). The sandbox must be stopped or crashed.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination artifact directory path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot-instance">Promise\<Snapshot></a></div>
    <div className="msb-param-desc">The created snapshot artifact.</div>
  </div>
</div>

## Snapshot static methods

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">builder()</span>

```typescript theme={null}
static builder(sourceSandbox: string): SnapshotBuilder
```

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await Snapshot.builder("baseline")
    .name("after-pip-install")
    .label("stage", "post-deps")
    .recordIntegrity()
    .create();
  ```
</Accordion>

Begin building a new snapshot of `sourceSandbox` (which must be stopped). The fluent builder is what powers the CLI internally. The bare-name and explicit-path destinations are mutually exclusive — call exactly one of [`.name()`](#name) or [`.path()`](#path). See [`SnapshotBuilder`](#snapshotbuilder) for all setters.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>sourceSandbox</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Name of the stopped sandbox to capture.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotbuilder">SnapshotBuilder</a></div>
    <div className="msb-param-desc">Builder for configuring the snapshot.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">open()</span>

```typescript theme={null}
static open(pathOrName: string): Promise<Snapshot>
```

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await Snapshot.open("after-pip-install");
  console.log(snap.digest);
  ```
</Accordion>

Open an existing snapshot artifact. Bare names resolve under the default snapshots directory; anything else is treated as a path. Cheap metadata validation only — does not read the upper file. Use [`verify()`](#snap-verify) for content checks.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare name (resolved under the default snapshots dir) or filesystem path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot-instance">Promise\<Snapshot></a></div>
    <div className="msb-param-desc">The opened snapshot.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">get()</span>

```typescript theme={null}
static get(nameOrDigest: string): Promise<SnapshotHandle>
```

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Snapshot.get("after-pip-install");
  console.log(h.digest, h.createdAt);
  ```
</Accordion>

Look up an indexed snapshot by digest, name, or path. Returns a lightweight [`SnapshotHandle`](#snapshothandle-class) backed by the local index row.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>nameOrDigest</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Name, digest (<code>sha256:...</code>), or path of an indexed snapshot.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandle-class">Promise\<SnapshotHandle></a></div>
    <div className="msb-param-desc">Index-backed handle.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">list()</span>

```typescript theme={null}
static list(): Promise<SnapshotHandle[]>
```

<Accordion title="Example">
  ```typescript theme={null}
  for (const h of await Snapshot.list()) {
    console.log(h.name ?? h.digest, h.sizeBytes);
  }
  ```
</Accordion>

List indexed snapshots from the local DB cache.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandle-class">Promise\<SnapshotHandle\[]></a></div>
    <div className="msb-param-desc">All indexed snapshot handles.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">listDir()</span>

```typescript theme={null}
static listDir(dir: string): Promise<Snapshot[]>
```

<Accordion title="Example">
  ```typescript theme={null}
  const found = await Snapshot.listDir("/mnt/external/snapshots");
  console.log(`${found.length} artifacts`);
  ```
</Accordion>

Walk a directory and parse each subdirectory's manifest. Does not touch the index — useful for inspecting external snapshot collections that were never imported. Skips entries that don't look like snapshot artifacts.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>dir</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Directory to scan for artifact subdirectories.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot-instance">Promise\<Snapshot\[]></a></div>
    <div className="msb-param-desc">Parsed snapshots found in the directory.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">remove()</span>

```typescript theme={null}
static remove(pathOrName: string, opts?: { force?: boolean }): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await Snapshot.remove("after-pip-install", { force: true });
  ```
</Accordion>

Remove a snapshot by path, name, or digest. Refuses if the snapshot has indexed children unless `force` is set.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path, name, or digest of the snapshot to remove.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>opts.force</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Remove even if the snapshot has indexed children. Defaults to <code>false</code>.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">reindex()</span>

```typescript theme={null}
static reindex(dir?: string): Promise<number>
```

<Accordion title="Example">
  ```typescript theme={null}
  const count = await Snapshot.reindex();
  console.log(`reindexed ${count} snapshots`);
  ```
</Accordion>

Walk the snapshots directory (default: the configured snapshots dir) and rebuild the local index. Returns the number of artifacts indexed.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>dir</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Directory to scan. Defaults to the configured snapshots dir.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Promise\<number></span></div>
    <div className="msb-param-desc">Count of artifacts indexed.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">export()</span>

```typescript theme={null}
static export(nameOrPath: string, out: string, opts?: ExportOpts): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await Snapshot.export("after-pip-install", "./baseline.tar.zst", {
    withImage: true,
  });
  ```
</Accordion>

Bundle a snapshot into a `.tar.zst` archive. When the snapshot has no integrity hash yet, one is computed and embedded in the bundled manifest so the receiver can verify. See [`ExportOpts`](#exportopts-interface) for bundling options.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>nameOrPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Name or path of the snapshot to bundle.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>out</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Output archive path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#exportopts-interface">ExportOpts</a></div>
    <div className="msb-param-desc">Bundling options. All fields default to <code>false</code>.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">import()</span>

```typescript theme={null}
static import(archive: string, dest?: string): Promise<SnapshotHandle>
```

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Snapshot.import("./baseline.tar.zst");
  console.log("imported", h.digest);
  ```
</Accordion>

Unpack a snapshot archive (`.tar.zst` or `.tar`) into the snapshots directory, verifying recorded integrity on the way in. Compression is detected from magic bytes.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>archive</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path to the archive to unpack.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dest</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination directory. Defaults to the snapshots directory.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandle-class">Promise\<SnapshotHandle></a></div>
    <div className="msb-param-desc">Handle to the imported snapshot.</div>
  </div>
</div>

<h2 id="snapshot-instance">
  Snapshot instance members
</h2>

A `Snapshot` is a snapshot artifact on disk. The artifact is a directory containing `manifest.json` and the captured `upper.ext4`. The directory is the source of truth; the local DB index is just a rebuildable cache. Returned by [`Snapshot.builder().create()`](#snapshotbuilder), [`Snapshot.open()`](#snapshot-open), [`handle.snapshot()`](#handle-snapshot), and [`handle.snapshotTo()`](#handle-snapshotto).

#### <span className="msb-recv">snap.</span><span className="msb-hn">path</span>

```typescript theme={null}
get path(): string
```

Path to the artifact directory.

#### <span className="msb-recv">snap.</span><span className="msb-hn">digest</span>

```typescript theme={null}
get digest(): string
```

Canonical content digest (`sha256:hex`). The snapshot's identity.

#### <span className="msb-recv">snap.</span><span className="msb-hn">sizeBytes</span>

```typescript theme={null}
get sizeBytes(): bigint
```

Apparent size of the captured upper layer in bytes (sparse on disk).

#### <span className="msb-recv">snap.</span><span className="msb-hn">imageRef</span>

```typescript theme={null}
get imageRef(): string
```

Image reference the snapshot was taken from.

#### <span className="msb-recv">snap.</span><span className="msb-hn">imageManifestDigest</span>

```typescript theme={null}
get imageManifestDigest(): string
```

OCI manifest digest of the pinned image.

#### <span className="msb-recv">snap.</span><span className="msb-hn">format</span>

```typescript theme={null}
get format(): "raw" | "qcow2"
```

On-disk format of the upper layer.

#### <span className="msb-recv">snap.</span><span className="msb-hn">fstype</span>

```typescript theme={null}
get fstype(): string
```

Filesystem type inside the upper (e.g. `"ext4"`).

#### <span className="msb-recv">snap.</span><span className="msb-hn">parent</span>

```typescript theme={null}
get parent(): string | null
```

Manifest digest of the parent snapshot, or `null` for a root.

#### <span className="msb-recv">snap.</span><span className="msb-hn">createdAt</span>

```typescript theme={null}
get createdAt(): string
```

RFC 3339 timestamp when the snapshot was created.

#### <span className="msb-recv">snap.</span><span className="msb-hn">labels</span>

```typescript theme={null}
get labels(): ReadonlyArray<readonly [string, string]>
```

User-supplied labels (sorted by key in canonical form), as `[key, value]` pairs.

#### <span className="msb-recv">snap.</span><span className="msb-hn">sourceSandbox</span>

```typescript theme={null}
get sourceSandbox(): string | null
```

Best-effort source-sandbox name, if recorded. `null` when the manifest has no source recorded.

#### <span className="msb-recv">snap.</span><span className="msb-hn">verify()</span>

```typescript theme={null}
verify(): Promise<SnapshotVerifyReport>
```

<Accordion title="Example">
  ```typescript theme={null}
  const report = await snap.verify();
  if (report.upper.kind === "verified") {
    console.log(`hash matches: ${report.upper.digest}`);
  } else {
    console.log("no integrity hash recorded");
  }
  ```
</Accordion>

Recompute the upper layer's content hash and compare against the manifest. Walks data extents only, so a 4 GiB sparse file with a few MB of data verifies in milliseconds. The report's `upper.kind` is `"notRecorded"` when the manifest has no integrity hash recorded.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotverifyreport-union">Promise\<SnapshotVerifyReport></a></div>
    <div className="msb-param-desc">Verification result.</div>
  </div>
</div>

## SnapshotBuilder

Fluent builder for a snapshot, returned by [`Snapshot.builder(name)`](#snapshotbuilder). Every setter mutates in place and returns `this`, so calls chain. Pick exactly one destination: [`.name()`](#name) or [`.path()`](#path).

#### <span className="msb-recv">.</span><span className="msb-hn">name()</span>

```typescript theme={null}
name(name: string): this
```

Set a bare name; the artifact lands under the default snapshots directory. Mutually exclusive with [`.path()`](#path).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare snapshot name.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">path()</span>

```typescript theme={null}
path(path: string): this
```

Set an explicit filesystem path for the artifact. Mutually exclusive with [`.name()`](#name).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination artifact directory path.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">label()</span>

```typescript theme={null}
label(key: string, value: string): this
```

Add a `key=value` label to the snapshot manifest. May be called repeatedly.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>key</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Label key.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>value</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Label value.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">force()</span>

```typescript theme={null}
force(): this
```

Overwrite an existing artifact at the destination instead of failing on conflict.

#### <span className="msb-recv">.</span><span className="msb-hn">recordIntegrity()</span>

```typescript theme={null}
recordIntegrity(): this
```

Compute and record a content-integrity hash of the upper layer at creation time, so the snapshot can be verified later or across a trust boundary.

#### <span className="msb-recv">.</span><span className="msb-hn">create()</span>

```typescript theme={null}
create(): Promise<Snapshot>
```

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await Snapshot.builder("baseline")
    .path("/data/snapshots/baseline-v2")
    .force()
    .recordIntegrity()
    .create();
  ```
</Accordion>

Capture the configured snapshot and return the resulting artifact.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot-instance">Promise\<Snapshot></a></div>
    <div className="msb-param-desc">The created snapshot artifact.</div>
  </div>
</div>

## Types

### SnapshotHandle <span className="msb-tag is-type">class</span>

Lightweight handle backed by an index row. Values are snapshotted from the index at construction time — call [`Snapshot.get()`](#snapshot-get) again for a fresh reading if needed. Handles from [`Snapshot.list()`](#snapshot-list) are read-only and throw on [`open()`](#snapshothandleopen) / [`remove()`](#snapshothandleremove); fetch a live handle via [`Snapshot.get()`](#snapshot-get) for those lifecycle methods.

<p className="msb-backref">Returned by <a href="#snapshot-get">Snapshot.get()</a>, <a href="#snapshot-list">Snapshot.list()</a>, <a href="#snapshot-import">Snapshot.import()</a></p>

| Member          | Type                                          | Description                                                                |
| --------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
| `digest`        | `string`                                      | Manifest digest (`sha256:hex`), the canonical identity.                    |
| `name`          | `string \| null`                              | Convenience name; `null` for digest-only entries.                          |
| `parentDigest`  | `string \| null`                              | Parent snapshot's manifest digest, or `null` for a root.                   |
| `imageRef`      | `string`                                      | Image reference the snapshot was taken from.                               |
| `format`        | `"raw" \| "qcow2"`                            | On-disk format of the upper layer.                                         |
| `sizeBytes`     | `bigint \| null`                              | Apparent size of the upper file at index time.                             |
| `createdAt`     | `Date`                                        | Snapshot creation time (from manifest).                                    |
| `path`          | `string`                                      | Local artifact directory path.                                             |
| `open()`        | `Promise<`[`Snapshot`](#snapshot-instance)`>` | Open and metadata-validate the underlying artifact.                        |
| `remove(opts?)` | `Promise<void>`                               | Remove the artifact and its index row; refuses on children unless `force`. |

<p className="msb-label" id="snapshothandleopen">snapshotHandle.open()</p>

```typescript theme={null}
open(): Promise<Snapshot>
```

Open and metadata-validate the underlying artifact. Throws if this handle is read-only (came from [`Snapshot.list()`](#snapshot-list)) — fetch a live handle via [`Snapshot.get()`](#snapshot-get) first.

<p className="msb-label" id="snapshothandleremove">snapshotHandle.remove()</p>

```typescript theme={null}
remove(opts?: { force?: boolean }): Promise<void>
```

Remove the artifact and its index row. Refuses if the snapshot has indexed children unless `force` is set. Throws if this handle is read-only.

```typescript theme={null}
const h = await Snapshot.get("after-pip-install");
const snap = await h.open();          // metadata-validated
await h.remove({ force: false });     // refuse if it has children
```

### ExportOpts <span className="msb-tag is-type">interface</span>

Bundle options for [`Snapshot.export()`](#snapshot-export). All fields default to `false`.

<p className="msb-backref">Used by <a href="#snapshot-export">Snapshot.export()</a></p>

| Field         | Type      | Description                                                    |
| ------------- | --------- | -------------------------------------------------------------- |
| `withParents` | `boolean` | Walk the parent chain and include each ancestor (no-op in v1). |
| `withImage`   | `boolean` | Include the OCI image cache so the archive boots offline.      |
| `plainTar`    | `boolean` | Skip zstd compression and write a plain `.tar`.                |

### SnapshotVerifyReport <span className="msb-tag is-type">union</span>

Result of [`snap.verify()`](#snap-verify). The `upper` discriminant is `"notRecorded"` when no integrity hash was stored at create time, or `"verified"` when the recorded hash matched the recomputed one.

<p className="msb-backref">Returned by <a href="#snap-verify">snap.verify()</a></p>

```typescript theme={null}
type SnapshotVerifyReport =
  | {
      readonly digest: string;
      readonly path: string;
      readonly upper: { readonly kind: "notRecorded" };
    }
  | {
      readonly digest: string;
      readonly path: string;
      readonly upper: {
        readonly kind: "verified";
        readonly algorithm: string;
        readonly digest: string;
      };
    };
```

| Field             | Type                          | Description                                         |
| ----------------- | ----------------------------- | --------------------------------------------------- |
| `digest`          | `string`                      | Snapshot's manifest digest.                         |
| `path`            | `string`                      | Artifact directory path.                            |
| `upper.kind`      | `"notRecorded" \| "verified"` | Whether an integrity hash was recorded and checked. |
| `upper.algorithm` | `string`                      | Hash algorithm (`"verified"` only).                 |
| `upper.digest`    | `string`                      | Recomputed upper-layer digest (`"verified"` only).  |