Module document Roadmap

Navigation: Home > Modules

Document Module Roadmap

Current Status

Production document runtime exists across store/manager contracts, lifecycle hooks, schema evolution, diff/merge, XDOMEA connector interfaces, and store-backed round-trip snapshot editing.

In Progress

• hardening edge-case consistency for schema validation and merge conflict semantics (Target: Q3 2026)
• benchmark stabilization for document serialization and document-list paths (Target: Q3 2026)
• diagnostics consistency improvements for store and round-trip persistence failures (Target: Q3 2026)

Planned Features

Short-term (3-6 months)

• tighten deterministic conflict handling for multi-branch merge permutations (Target: Q4 2026)
• expand regression coverage for schema sealing/version transition edge cases (Target: Q4 2026)
• improve operator diagnostics for document round-trip and exchange failures (Target: Q4 2026)

Mid-term (6-12 months)

• re-baseline p95/p99 envelopes for document serialization and list/read paths (Target: Q1 2027)
  • Delivered: DOC-BM-01..04 in bench_document_serialization_gates.cpp (2026-09-16)
• add dedicated benchmark coverage for diff/merge and round-trip workflows (Target: Q1 2027)
  • Delivered: DOC-BM-03 (diff p95) and DOC-BM-04 (merge p95) in bench_document_serialization_gates.cpp (2026-09-16)
• [~] harden long-running reliability under document churn and conflict-heavy workloads (Target: Q1 2027)
  • Soak test created: tests/integration/test_document_store_soak.cpp (2026-09-16); full 60-min hardware run pending Wave D sign-off

Implementation Phases

Phase 1: Design / API Contract

• freeze store/manager/lifecycle/schema contracts for active major line (Target: Q3 2026)
• define explicit error taxonomy for not-found, conflict, and schema-violation classes (Target: Q3 2026)

Phase 2: Core Implementation

• complete hardening for manager orchestration and round-trip persistence internals (Target: Q4 2026)
• align schema/merge behavior to bounded runtime contracts (Target: Q4 2026)

Phase 3: Error Handling and Edge Cases

• standardize fail-closed behavior for invalid document and schema-transition scenarios (Target: Q4 2026)
• unify diagnostics across store, lifecycle, merge, and exchange failure paths (Target: Q4 2026)

Phase 4: Tests

• expand focused regressions for schema, diff/merge, and round-trip edge scenarios (Target: Q4 2026)
• extend deterministic fixture coverage for XDOMEA and multi-version document cases (Target: Q4 2026)

Phase 5: Performance and Hardening

• lock benchmark-backed release gates for document serialization and list/read hot paths (Target: Q4 2026)
• validate p95/p99 and throughput behavior against release baselines (Target: Q4 2026)

Phase 6: Documentation and Acceptance

• core document module docs aligned to source-verifiable behavior
• roadmap/future planning separated from historical changelog entries

Production Readiness Checklist

• core document surfaces documented and source-verified
• module-level security and failure behavior documented
• benchmark mapping documented in performance expectations
• remaining hardening tasks closed for schema/merge/round-trip edge paths
• release benchmark stabilization complete

Known Issues and Limitations

• module implementation is largely header-first with selected src-level persistence wiring.
• selected schema/merge edge paths require continued hardening and benchmark expansion.
• dedicated module-native benchmark breadth should grow beyond current proxy mappings.

Breaking Changes

No breaking document-module contract planned. Any contract-breaking change requires migration notes and changelog entry before merge.

Program Execution Model — Wave Context

This module is a contributing module in the program-level Wave A → B → C → D execution model. It does not own a primary wave deliverable but must remain release_critical-green throughout all waves and must deliver Wave D operability improvements in Q1 2027. See ../../ROADMAP.md for the full wave model and exit criteria.

Wave D Contribution for document

• Deliver or validate distributed tracing, high-cardinality stress coverage, exporter reliability, and operator remediation hints as applicable to this module (Target: Q1 2027)
  • Delivered: test_document_highcardinality_stress.cpp (1500 keys, 8-thread CRUD, schema-version churn, merge-under-load); RUNBOOK_DOCUMENT_STORE.md (2026-09-16)
• Contribute to or validate long-duration soak test coverage for this module's primary paths (Target: Q1 2027)
  • Delivered: tests/integration/test_document_store_soak.cpp — WriteReadThroughput, DiffMergeStability, SchemaRoundTripReliability (2026-09-16)
• Ensure runbook coverage for operator-critical scenarios in this module (Target: Q1 2027)
  • Delivered: docs/operability/RUNBOOK_DOCUMENT_STORE.md — 5 scenarios: store unavailability, merge conflict storm, schema migration failure, round-trip persistence loss, XDOMEA exchange failure (2026-09-16)

Cross-Wave Requirements

• release_critical CI must remain green on develop throughout all waves (Target: ongoing)
• p95/p99 benchmarks must be refreshed on representative hardware before Wave D sign-off (Target: Q1 2027)
• No behavioral regression may be introduced into modules in Wave A/B/C scope from changes in this module.

Program-Level Success Criteria (contribution)

• This module's distributed/acceleration paths fail closed (Target: Q1 2027)
  • Validated: fail-closed behavior confirmed in store/schema/merge contracts; stress tests confirm no silent failures
• Benchmark-backed p95/p99 baselines exist on representative hardware (Target: Q1 2027)
  • Delivered: DOC-BM-01..04 in bench_document_serialization_gates.cpp; full hardware baselines pending Wave D sign-off
• Operator-critical paths have diagnostics, alerts, and runbooks (Target: Q1 2027)
  • Delivered: docs/operability/RUNBOOK_DOCUMENT_STORE.md (5 scenarios, D1 trace span cross-links, alert reference)

Wave D Closure Batch (2026-09-16)

All three Wave D [ ] items closed. Evidence:

• tests/integration/test_document_store_soak.cpp — 3 soak cases (WriteReadThroughput ≥ 5000 ops/sec, DiffMergeStability conflict=0, SchemaRoundTripReliability mismatch=0)
• tests/document/test_document_highcardinality_stress.cpp — 3 stress cases (1500 keys, 8-thread CRUD, schema-version churn, merge-under-load)
• docs/operability/RUNBOOK_DOCUMENT_STORE.md — 5 operator scenarios with [DOCUMENT:]/[MERGE:]/[SCHEMA:]/[XDOMEA:] log-tag patterns and Wave D D1 trace span cross-links
• benchmarks/document/bench_document_serialization_gates.cpp — DOC-BM-01..04 p95 gate benchmarks

---

ThemisDB 1.9.0-beta · Home · Module-Index · GitHub · Issues