---
title: "Orleans.Lattice.Storage.File"
url: "https://nsta1.github.io/Orleans.Lattice/docs/lattice.storage.file/README.html"
source: "https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/docs/lattice.storage.file/README.md"
package: "Orleans.Lattice.Storage.File"
version: "9.9.0"
documents: "Orleans.Lattice 9.9.0 (release line 9.9)"
built: "2026-10-04"
all-pages: "https://nsta1.github.io/Orleans.Lattice/llms.txt"
bundle: "https://nsta1.github.io/Orleans.Lattice/docs/lattice.storage.file/llms-full.txt"
---
# Orleans.Lattice.Storage.File

Part of the [documentation map](../index.md).

Durable, cloud-free **local disk** WAL provider for [Orleans.Lattice](../../README.md). It plugs into the public `IWalStorageProvider` seam so a single-cluster deployment can persist its commit log to a mounted directory - crash-safe across silo restarts - without an external storage account.

## What is it?

`Orleans.Lattice.Storage.File` is the optional on-disk WAL backend for the core lattice:

- **Durable WAL storage.** `FileWalStorageProvider` stores each WAL partition of each tree as a segmented, append-only file on the local filesystem and implements the public `IWalStorageProvider` contract.
- **All-or-nothing batch append.** Each batch is framed as a run of data records sealed by a single commit trailer and made durable with one write plus fsync; a crash before the trailer is durable rolls the whole batch back on recovery.
- **Restart recovery.** Activation-time reconciliation rolls every committed batch forward, discards a torn tail, and reclaims trimmed space, so after a crash the log ends cleanly at its last committed batch; an honest offset gap left by a failed append is preserved, never renumbered.
- **Drop-in registration.** `AddFileWalStorage` displaces the in-memory WAL backend installed by core lattice registration, and wires the durable-WAL garbage-collection stack alongside it.

As a WAL store it matches the observable durability guarantees of the [Azure Table Storage provider](../lattice.storage.azuretable/README.md) without any cloud dependency. Tree state - each leaf's state row and its snapshots - still lives in the grain storage provider `AddLattice` registers, so a durable deployment pairs it with a durable grain storage provider, which must enforce ETags on write (see [The grain storage provider must enforce ETags](../lattice/configuration.md#the-grain-storage-provider-must-enforce-etags)); that pairing makes it the enabler for a single-container, "codebase memory in a box" deployment (see the [RepoContext MCP](../lattice.api.mcp.repocontext/README.md) package and its [container sample](../../samples/RepoContextContainer/README.md), which uses Orleans ADO.NET grain storage over a single SQLite file).

Core WAL semantics, the provider seam, and placement are covered in [WAL Storage Providers](../lattice/wal-storage-providers.md).

## Core Properties

- **Per-shard ordering.** Offsets are stored verbatim and read back in ascending order within each `(tree, shard)` stream.
- **Batch atomicity.** A successful append is visible as a complete batch; a torn or uncommitted trailing batch leaves no visible partial state after recovery.
- **Crash recoverability.** Interrupted appends are reconciled before normal reads and writes rely on the stored tail.
- **Self-compacting.** Trimmed payload bytes are physically reclaimed by rewriting a shard's segment file once enough dead space accumulates.
- **Published to NuGet** as `Orleans.Lattice.Storage.File`, released under `lattice.storage.file-v<X.Y.Z>` tags.

## Public surface

| Type or member | Role |
|---|---|
| `FileWalStorageProvider` | Public `IWalStorageProvider` implementation (also `IDisposable`) that stores one `wal.log` per `(tree, shard)` stream under `FileWalStorageOptions.RootDirectory`. Its public constructor, `FileWalStorageProvider(IOptions<FileWalStorageOptions>, Serializer<WalRecord>)`, builds a provider without the routing reader, so its filtered replay reads decode every record they examine; `AddFileWalStorage` is the registration that supplies one. |
| `FileWalStorageOptions` | Public options type for the root directory, flush policy, compaction thresholds, and read-page byte ceiling, with public `Default*` constants for the compaction and read-page defaults. |
| `LatticeFileServiceCollectionExtensions.AddFileWalStorage` | Registration extension that installs the file WAL provider, its options validator, and the durable-WAL garbage-collection wiring on an `ISiloBuilder`. |

## Quick Start

Install the package and register it on the silo that owns the WAL:

```shell
dotnet add package Orleans.Lattice.Storage.File
```

```csharp verify
using Orleans.Lattice.Storage.File;

siloBuilder.AddFileWalStorage(options =>
{
    options.RootDirectory = "/data/wal";
});
```

Register it alongside `AddLattice(...)` on the silo that owns the WAL. The registration order does not matter: `AddFileWalStorage` displaces the in-memory baseline whether it runs before or after `AddLattice`.

## Reference

- [Configuration](configuration.md) - every `FileWalStorageOptions` knob, default, and validation rule.
- [Architecture](architecture.md) - the on-disk layout, the append/commit framing, the durability contract, compaction, and recovery behaviour.

Related package docs:

- [Core WAL Storage Providers](../lattice/wal-storage-providers.md) - the core provider seam, in-memory default, and WAL placement.
- [Core WAL](../lattice/wal.md) - single-cluster WAL commit and replay semantics.
- [Azure Table WAL provider](../lattice.storage.azuretable/README.md) - the cloud-backed alternative with the same durability contract.