Feature/esp jsondb v2

[zekageri]

Summary

• Merges the feature/esp-jsondb-v2 branch into main and finalizes the ESPJsonDB v2 release line.
• Reworks the library around thin public facades plus internal runtime/store ownership, adds durable .jdb record storage with persisted metadata, and moves generic file APIs behind db.files().
• Updates tests, examples, docs, library metadata, and CI so the v2 API/storage model is the documented and buildable default.
• Related issues: none linked for this branch merge.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Documentation update
• Build/CI

Details

• Introduces the v2 storage/runtime model: durable .jdb records, persisted _id/createdAtMs/updatedAtMs/revision/flags, revision-aware update paths, collection load policies (Eager, Lazy, Delayed), explicit snapshot modes, and a dedicated FileStore.
• Refactors ESPJsonDB and Collection into thin public facades so runtime-owned state is no longer exposed in public headers.
• Removes deprecated/compatibility APIs and config knobs: getDiag(), getAllCollectionName(), unRegisterSchema(), direct file helpers on ESPJsonDB, cacheEnabled, coldSync, and delayedCollectionSyncArray.
• Updates README, changelog, examples, library metadata, and CI to reflect the v2 API and release semantics.
• Reviewer context: decode compatibility is preserved for the interim duplicated-flags v2 envelope, but v2 does not provide automatic on-disk compatibility with legacy v1 .mp files.

Testing

• Builds locally
• Unit tests added/updated
• Tested on target hardware/device (if applicable)

Describe how you tested the changes. Include commands, logs, or screenshots if helpful.

• Built examples/FileStreaming locally with PlatformIO for esp32dev:

/home/zekageri/.platformio/penv/bin/pio ci examples/FileStreaming --board esp32dev --lib=. --project-option "platform=https://github.com/pioarduino/platform-espressif32.git" --project-option "build_unflags=-std=gnu++11" --project-option "build_flags=-std=gnu++17"

• Verified the branch is free of whitespace/diff formatting issues with:

git diff --check main...HEAD

• Updated the hardware-oriented test harness to cover doc codec compatibility, optimistic conflict handling, collection budget enforcement, delayed collection loading, snapshot metadata, and the db.files() API migration.
• Full on-device execution of the hardware test suite was not run in this pass.

Compatibility / Breaking Changes

• This is a breaking v2 merge.
• File APIs now go through db.files(). Example: db.writeTextFile(...) -> db.files().writeTextFile(...); cancelFileUpload(...) -> db.files().cancelUpload(...); getFileUploadState(...) -> db.files().getUploadState(...).
• Diagnostics/collection/schema API renames: getDiag() -> getDiagnostics(), getAllCollectionName() -> listCollectionNames(), unRegisterSchema() -> unregisterSchema().
• ESPJsonDBConfig::cacheEnabled, coldSync, and delayedCollectionSyncArray are removed. Use configureCollection(name, CollectionConfig{...}) for per-collection load behavior.
• On-disk format changed from legacy .mp payload files to .jdb records with persisted _meta. Existing v1 data is not auto-read by v2.
• Snapshot payloads now include _meta; downstream snapshot consumers need to accept the new shape.

Risks and Mitigations

• Potential risk: the runtime/storage refactor touches core persistence, collection lifecycle, and file I/O paths.
• Mitigation: added coverage for codec compatibility, conflicts, budgets, delayed loads, file operations, and snapshot metadata; public headers were reduced to a thinner surface to limit future coupling.
• Potential risk: downstream compile/runtime breaks from v2 API removals.
• Mitigation: README, changelog, examples, and metadata were updated to use the new API exclusively and document the migration path.

Checklist

• Code follows project style and conventions
• All tests pass locally
• Documentation updated (README, examples, comments)
• No secrets, credentials, or sensitive data committed
• Linked issue(s) and relevant context provided

Environment

• Toolchain/SDK versions: PlatformIO Core 6.1.19; pioarduino platform-espressif32 55.3.37+sha.a9fac07; framework-arduinoespressif32 3.3.7; toolchain-xtensa-esp-elf 14.2.0+20251107; ArduinoJson 7.4.3; StreamUtils 1.9.2; ESPBufferManager 0.1.0+sha.a72e21b
• OS and version: Linux Mint 22.3 (Linux 6.17.0-19-generic x86_64)
• Other relevant environment details: branch feature/esp-jsondb-v2, head 78daa4f