hidane 0.5.0

Use 0.5.1 instead. Commits with many writes are slow in this release: a commit of 500 writes takes about twelve times as long as in 0.4.0 (#279).

hidane 0.5.0 adds the tools around the emulator: it checks a Firebase project, moves it off the official emulator, measures what that saves, and collects what a bug report needs. It also runs under Testcontainers in place of the Cloud SDK image, and fixes the first two batches of differences that differential fuzzing found against the official emulator.

Verified against the official Cloud Firestore emulator v1.22.0, as firebase-tools 15.33.0 downloads it. Per-client versions are in docs/sdk-certification.md.

Highlights

• hidane doctor checks a Firebase project before it moves to hidane, without running or changing anything:

  • firebase.json and the emulators it starts
  • the Security Rules
  • the SDK and firebase-tools versions, each marked compatible, likely-compatible or not verified
  • the CI workflows and scripts that start the emulators

• hidane migrate shows the changes as a diff and makes them with --apply:

  • hidane exec -- in front of firebase emulators:exec
  • hidane-dev/setup-hidane where actions/setup-java only served the Firestore emulator

  It refuses to write over uncommitted changes and keeps backups.

• hidane benchmark measures your own test command against both emulators on your machine (--compare-official). hidane benchmark savings turns the medians into CI time saved per month, and into cost at a rate you give. It also prints a Markdown case-study block. Figures are medians of your own measurement, with no "N× faster".

• hidane report prints a redacted diagnostic bundle to attach to a bug report:

  • versions, OS, the project scan
  • which official emulator versions are cached
  • a sanitized firebase.json

  Project IDs, keys, tokens, emails and paths are removed. It writes locally and sends nothing.

• Testcontainers: hidane's image works in Testcontainers' Firestore modules for Java and Node by changing only the image name (it reads the gcloud … emulators firestore start command they pass). It is verified with a generic container for Python and Go. See docs/testcontainers.md.

New CLI

Command	Output
hidane doctor [--path DIR] [--format text|json]	hidane.doctor/1
hidane migrate [--path DIR] [--apply [--force]] [--format text|json|patch]	hidane.migrate/1
hidane benchmark [--compare-official] … [-- <command>], hidane benchmark render, hidane benchmark workload	result schema 1
hidane benchmark savings <result.json|-> --runs-per-month N [--cost-per-minute X --currency C]	bench/schema/savings.schema.json
hidane report [--path DIR] [--format markdown|text|json] [--output FILE]	hidane.report/1

The JSON schemas and exit codes of these commands are stable surfaces from this release on (docs/versioning.md).

Compatibility

These answer as the official emulator does. Each is recorded from it and replayed by the tests (#262):

• :batchGet with the same document named more than once returns it once, at its first position.
• Several writes to one document in a commit each report the commit's outcome for that document. For example, there is no updateTime when the last write deletes it.
• A PATCH or POST with an invalid read mask (mask.fieldPaths) writes nothing. Reserved and empty field paths are refused.
• A transform on a field and on a field nested in it, in one write, is refused.
• A RunQuery or RunAggregationQuery without a structured query, a filter of no kind, and sum / avg without a collection are refused. Array-contains in separate branches of an or is allowed.
• Query checks run in the official emulator's order: filters, orders, limit, collection, key filters, cursors and the query vector.

New machine-readable records of what was verified:

• docs/sdk-certification.json
• docs/compatibility.json (the hidane × firebase-tools × official emulator matrix)
• docs/parity-exceptions.json (the intentional differences, each with its kind)

Benchmark

• The canonical benchmark runs both emulators side by side on one dedicated AWS c7i.xlarge, nightly and for each release. Results are published with every sample in hidane-dev/benchmark-results (CC BY 4.0).

• In that environment, the v0.4.0 release run measured these medians:

  Measurement	Official emulator	hidane
  Startup to port	941 ms	1.56 ms
  Idle RSS	148 MiB	7.8 MiB
  firebase emulators:exec around 200 tests	6.75 s	1.67 s

• New scenario: writes with a listener attached (listen_writes). In cargo test it is a regression check that batch writes stay flat as documents accumulate.

Migration

• hidane-dev/setup-hidane is on GitHub Marketplace. Its migrate sub-action opens the migration as a pull request when you start it by hand; it arrives with setup-hidane v1.1.0, after this release.
• examples/ are copy-paste projects that CI runs against hidane: firebase-admin (Node), Python, Go, a Firestore-triggered function, @firebase/rules-unit-testing and a GitHub Actions workflow.

Fuzzing and quality

• A differential fuzzer (tools/fuzz/) sends the same generated requests to the official emulator and to hidane, then minimizes each difference it finds. It runs daily.
• The first triage sorted 143 differences, all of which v0.4.0 already had. This release fixes 39 of them on the seed they were found with. The rest are tracked in #262.
• An upstream watcher and canaries check new firebase-tools, official emulator and SDK releases against hidane before they are verified.

Security and supply chain

• Release binaries build reproducibly: the same commit gives the same bytes on Linux and macOS (docs/reproducible-builds.md).
• Each archive has a CycloneDX SBOM, attested like the archive's build provenance. The container image carries provenance and SBOM attestations too (docs/verifying-releases.md).
• SECURITY.md is revised, and OpenSSF Scorecard runs on the repository. Releases are immutable once published.

Breaking changes

None to a stable surface. The compatibility fixes above can change what a test written against hidane's earlier answers sees, as docs/versioning.md describes.

Known limitations

• The macOS binaries are not signed or notarized: a browser download needs xattr -d com.apple.quarantine hidane (docs/verifying-releases.md).
• iOS, Android and the native FlutterFire platforms are not verified yet (#266, #267). Neither are Datastore mode and the Enterprise edition's pipelines.
• 104 differences found by fuzzing are still open on the original seed (#262). Most concern which error comes first when a request has several problems.