Skip to content

ResonanceDB Server v2.0.2

Latest
Latest

Choose a tag to compare

View all tags
@LexProfi LexProfi released this 04 Sep 12:06
· 1 commit to main since this release
v2.0.2
81bfe9a

ResonanceDB Server v2.0.2

This release introduces a new durability and indexing layer for ResonanceDB Server, together with an important correction to the query ranking contract.

Version 2.0.2 adds a Write-Ahead Log and delta-buffered write path, a persisted IVF waveform indexing pipeline with Vamana graph support, and automatic background index rebuilds. It also unifies standard and detailed query execution around a single deterministic ranking rule: resonance energy descending, then pattern ID ascending.

The result is a substantially more mature storage and retrieval path while preserving the corpus-scoped REST architecture introduced in v2.0.0.

Highlights

  • WAL-backed write path

    • Write-Ahead Log support for mutation recovery
    • configurable STRICT, GROUP, and ASYNC durability modes
    • in-memory delta buffering before segment sealing
    • WAL replay during store initialization
    • size-triggered and periodic delta sealing
    • backpressure protection for an overgrown delta buffer

  • Waveform indexing pipeline

    • spherical k-means centroid partitioning
    • persisted centroid index and posting sidecar
    • IVF candidate routing
    • Vamana graph navigation within eligible partitions
    • exact resonance rescoring of selected candidates
    • exact scoring of unsealed delta entries
    • automatic background index construction and rebuild

  • Canonical energy ranking

    • query ordering is now defined exclusively as:

      • energy DESC
      • id ASC as the deterministic tie-breaker

    • identity bonuses, exact-match bonuses, and resonance-zone metadata no longer alter result ordering

    • queryDetailed now enriches the same ranked result set produced by query

    • CORE, FRINGE, and SHADOW remain diagnostic classifications only

  • Index correctness and equivalence controls

    • exact-equivalence mode for indexed-versus-exhaustive query verification
    • epsilon-bounded phase-1 candidate selection
    • exact delta-buffer scoring
    • candidate deduplication across index stages
    • improved numerical stability in persisted sidecar scoring

Write Path & Recovery

When WAL support is enabled, mutations are appended to the Write-Ahead Log and staged in the in-memory delta buffer before being sealed into the persistent segment store.

WAL replay restores pending mutations when a store is reopened.

The write path supports three durability modes:

  • STRICT — synchronous durability per write
  • GROUP — grouped durable writes
  • ASYNC — asynchronous WAL flushing

The Docker runtime enables WAL with GROUP durability.

Delta sealing is no longer dependent only on reaching the size threshold. A periodic seal check is also performed, with a default interval of 30 seconds, allowing low-volume corpora to move pending entries out of memory without waiting for the normal seal threshold.

Seal handling has also been hardened:

  • entries that fail during a seal attempt are returned to the active delta buffer instead of being silently discarded
  • same-LSN replacement handling now preserves the correct tombstone visibility
  • WAL checkpoint failures are surfaced through diagnostic output

Waveform Index

Version 2.0.2 introduces the first persisted waveform index pipeline in ResonanceDB.

The index architecture combines:

  1. IVF L1 routing

    • waveform unfolding
    • spherical k-means clustering
    • centroid-based partition selection
    • persisted centroid metadata

  2. Partition candidate search

    • persisted posting sidecars
    • Vamana graph support for eligible partitions
    • delta-index integration for recently written data

  3. Exact final scoring

    • index stages are used for candidate generation
    • final ranking is determined by the ResonanceDB resonance kernel
    • entries still resident in the delta buffer are scored exactly and merged into the result set

If the persisted index is unavailable, the server can schedule an index rebuild in the background. Rebuilds are also triggered as accumulated index deltas cross the configured threshold.

An exact-equivalence mode is available for correctness and metamorphic testing of indexed execution against exhaustive query behavior.

Query Ranking

This release establishes a single canonical ranking contract across the retrieval API.

Results are ordered by:

  1. resonance energy, descending
  2. pattern ID, ascending, when energies are equal

No auxiliary classification participates in this ordering.

In particular, resonance zones remain available in detailed results:

  • CORE
  • FRINGE
  • SHADOW

but are diagnostic metadata only.

queryDetailed now executes the canonical query path first and enriches those results with phase and zone information afterwards. This prevents detailed diagnostics from producing a different top-K ordering from the standard query path.

The same ranking contract is applied to delta-buffer results before they are merged with persisted-store candidates.

Index Correctness Improvements

Several changes harden recall and deterministic behavior in the new index path:

  • delta-buffer entries are exact-scored rather than approximately filtered
  • candidates produced by multiple index stages are deduplicated before final scoring
  • phase-1 candidate cutoffs include an epsilon bound to avoid unstable exclusions near the selection boundary
  • persisted sidecar scoring uses more stable numerical accumulation
  • indexed execution can be forced into exact-equivalence mode for exhaustive comparison
  • indexed and non-indexed paths share the same final ranking contract

These changes are specifically intended to keep indexing an acceleration layer rather than allowing index-internal heuristics to redefine retrieval semantics.

REST Validation

REST request validation has been tightened in v2.0.2.

The server now:

  • rejects non-finite waveform values such as NaN and Infinity by default
  • rejects missing or blank IDs on replace and delete operations
  • requires composite-query weights to be present
  • requires the number of weights to match the number of input patterns
  • rejects null or non-finite composite weights

Invalid requests are rejected before reaching the storage and scoring layers.

Reliability & Diagnostics

Additional correctness and operational hardening includes:

  • silent exception swallowing removed from affected storage, index, and REST paths
  • failures in cleanup, rebuild, sealing, and related background operations now produce diagnostic output
  • WAL replay distinguishes recoverable partial-tail records from non-tail corruption
  • index rebuild failures are surfaced rather than silently ignored
  • dedicated recovery, delta-seal, ANN, Vamana, and query-consistency test coverage

Build & Deployment

The Docker runtime has been updated for the new storage and indexing path.

Changes include:

  • WAL enabled by default in the Docker runtime
  • GROUP WAL durability enabled by default
  • waveform index enabled by default
  • IVF probe configuration included in the container runtime
  • JVM heap profile increased for indexed operation
  • adjusted container healthcheck timing
  • improved handling of CRLF gradlew line endings during Docker builds

WAL and index behavior remain configurable through ResonanceDB system properties outside the Docker runtime.

Compatibility

Version 2.0.2 preserves the corpus-scoped REST route structure introduced in v2.0.0.

There are no route changes to the existing REST API.

However, this release intentionally changes retrieval and validation behavior:

  • query ranking now follows the canonical pure-energy contract
  • query and queryDetailed return results using the same ordering
  • malformed non-finite waveform values are rejected by default
  • replace/delete IDs and composite-query weights are validated more strictly
  • WAL and waveform-index operation may create additional persistent files when those features are enabled

Applications that depended on the previous auxiliary ranking behavior should validate expected top-K ordering when upgrading.

Versioning

This release corresponds to Git tag:

v2.0.2

The runtime version is derived from the project Gradle configuration at build time.

Legal Notice

This release is provided under the terms of the repository LICENSE.

No additional rights are granted by this release note.
All rights and permissions are governed solely by the applicable license files in the repository.

For licensing inquiries:
license@evacortex.ai

Assets 2
Loading