Fresh 0.2.0 pluggable storage and formatting

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.

[zekageri]

Summary

Redesigns Fresh 0.2.0 around owned storage backends and a direct application-file facade, and adds a destructive whole-volume formatting lifecycle.

Public API

• FreshConfig contains database behavior only
• Explicit backends are passed to db.init(path, config, storage) and become Fresh-owned
• db.init(path, config) remains as a convenient default-LittleFS overload
• Application files use db.storage() directly
• Adds FreshInitResult as the initialization result type
• Adds Fresh::format() for explicitly destructive whole-volume formatting

Fresh db;
FreshInitResult initialized = db.init("/fresh");
if (!initialized) return;
FreshResult formatted = db.format();
if (!formatted) return;
// The same Fresh instance is now an empty initialized database.
db.createModel("settings");

Destructive formatting

format() deletes the Fresh database, application files accessed through db.storage(), and unrelated files on the same configured filesystem. It is intentionally different from dropAllModels().

The operation:

• blocks new database and application-storage operations
• cancels backup work and stops background sync without a final write
• closes and invalidates tracked FreshFile handles
• formats the complete backend
• invalidates retained FreshModel handles
• rebuilds the database root and an empty durable manifest
• restarts the sync task and preserves existing storage facades after success
• fails closed when an error occurs after native formatting begins

LittleFS, SDSPI, SDMMC, and eMMC use their ESP-IDF native format paths. Custom backends remain unsupported by default and can opt in with supportsFormat() and formatBackend().

Built-in storage

• FreshLittleFSStorage through ESP-IDF LittleFS VFS
• FreshSDStorage through ESP-IDF SDSPI or SDMMC
• FreshEMMCStorage with 1-, 4-, and 8-bit SDMMC configuration
• Fresh-owned custom FreshStorage and FreshFileBackend implementations

Fresh does not include or synchronize Arduino's global LittleFS, SD, or SD_MMC objects.

Application files and lifecycle

• db.storage() exposes open/read/write, complete-file helpers, existence and size queries, recursive directory creation, listing, removal, rename, and capacity diagnostics
• The configured Fresh database root is protected from application operations
• Move-only FreshFile handles retain explicit sync(), close(), and syncAndClose() durability boundaries
• Short writes and read, sync, close, capacity, and existence-query failures are propagated
• Open application files cause deinit() to return FreshStatus::Busy
• Backup archives can use the same selected backend without a separate filesystem wrapper

Regression coverage

Adds StorageFormatRegressionTest with a custom in-memory backend covering:

• unsupported formatting without lifecycle disruption
• complete-volume deletion
• stale file and model handle invalidation
• retained storage-facade usability after success
• durable empty database bootstrap
• continued persistence after formatting and reinitialization
• repeated formatting
• native formatter failure and fail-closed behavior

Validation

The implementation passed structural source checks for balanced delimiters and the production-source audit patterns. The repository CI build matrix is the authoritative compilation validation for ESP32, ESP32-C3, ESP32-S3, and ESP32-P4 and will run on this PR update.

Hardware qualification

Physical validation remains required for whole-volume formatting and remounting on representative LittleFS, SDSPI, SDMMC, and eMMC hardware, including absent/full media, card removal, power loss, and board-specific power/reset sequencing.