# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.3.1] - 2026-02-17

### Fixed
- **3897/3897 TCK scenarios** (was 3874/3897) — 23 scenarios now execute and pass:
  - CucumberExpression bug: `(text)` is optional, not literal parens. `the result should be (ignoring element order for lists):` step never matched. Fixed with `regex = r"...\(...\)..."` in all 4 TCK runners
  - `[:TYPE]` relationship notation now parsed and compared by type in `values_match`
  - `+labels` side-effect counting corrected: counts new label types to DB, not per-node assignments
  - Nested node list comparison `[[(:A), (:B)], ...]` now uses bipartite matching via `values_match`
- Removed stale `@skipStyleCheck` / `@skipGrammarCheck` tags from feature files (were no-ops in cucumber-rs)

## [0.3.0] - 2026-02-17

### Added
- **Monitoring**: `GraphMetrics` (7 atomic counters) and `CircuitBreaker` in `src/telemetry/` behind `metrics`/`self-heal` feature flags
- **Python metrics API**: `on_execute(callback)` and `metrics()` on all 4 graph classes
- **Partition node HTTP observability**: axum server on port 9090 (`/health`, `/ready`, `/metrics` in Prometheus text format)
- **etcd retry**: Exponential backoff (250ms→30s, 10 attempts) for distributed partition startup
- **Snapshot restore**: Auto-restore from snapshot on empty partition node startup
- **Operator health watch**: `PodHealthWatcher` — Arrow Flight health probe per pod, delete after 3 consecutive failures
- **Operator metrics extended**: `partition_health_failures` and `partition_restarts` Prometheus counters per pod
- **K8s StatefulSet probes**: HTTP liveness (`/health`) and readiness (`/ready`) probes on port 9090
- **ServiceMonitor**: `operator/deploy/partition-service-monitor.yaml` for Prometheus Operator scraping
- **`.pyi` stubs + `py.typed`**: Full IDE autocomplete support for all 4 backends (PEP 561 compliant)
- **Python temporal types**: `Date`, `LocalDateTime`, `LocalTime`, `Duration` return native `datetime.date/datetime/timedelta` objects
- **cargo-deny**: License and advisory compliance CI job; `deny.toml` with allowlist

### Fixed
- **100% TCK compliance**: 3,874/3,897 scenarios pass (23 skipped, **0 failed**) — was 3,859
  - Root cause: `Integer / Integer` was incorrectly returning `Float`; now returns `Integer` per OpenCypher spec
- All 64 Clippy warnings eliminated (structural refactors, no suppressions)
- All rustdoc link/HTML warnings cleared
- `src/lib.rs` doc comments updated to reflect 100% compliance

### Changed
- Version bumps: `ocg = "0.3.0"`, `ocg-operator = "0.3.0"`
- `description` in `Cargo.toml` and `pyproject.toml` updated to "100% openCypher-compliant"
- New Cargo features: `metrics = []`, `self-heal = []`

## [0.2.9] - 2026-02-17

### Changed
- Remove `NXCypherCompat` backward-compatibility shim (clean break from nxcypher migration path)
- Replace all bare "Cypher" terminology with "OpenCypher" across source, docs, and Python bindings
- Remove 130+ session/plan/intermediate documents from git tracking (`fixplan/`, `docs/archive/`, etc.)

### Fixed
- All `nxcypher` code prefixes renamed to `ocg` in examples, deployment configs, and test scripts
- `RUST_LOG` filters updated from `nxcypher=*` to `ocg=*` in `deployment/`
- `test_python_setup.sh` updated to import `ocg` instead of `nxcypher_networkit`

## [0.2.8] - 2026-02-17

### Added
- Graph dump/restore (`save()` / `load()`) for all 4 backends with full metadata:
  `format_version`, `ocg_version`, `backend`, `created_at`, `nodes`, `edges`
- `GraphDump` struct in `src/graph/serialization.rs` with `dump_to_file` / `load_dump` functions

### Fixed
- Algorithm count corrected to 31 (was 40+) across README, `__init__.py`, `lib.rs`
- TCK compliance stat corrected to 99%+ / 3,859/3,897 (was "100%")
- `pyproject.toml` description updated to match reality

## [0.2.7] - 2026-02-17

### Changed

#### Codebase Fully Aligned to `ocg` Brand
- All remaining `nxcypher` references replaced with `ocg` in `src/lib.rs`, `src/procedures/mod.rs`,
  `src/python.rs`, `python/ocg/pandas_compat.py`, and `README.md`
- README code examples updated: `nxcypher = "0.1"` → `ocg = "0.2"`, `use nxcypher::` → `use ocg::`
- `README.md` comparison section retitled; removed internal project cross-references

#### Algorithm Coverage Verified: All 4 Backends Identical
- Confirmed all 4 graph classes (`Graph`, `NetworKitGraph`, `RustworkxGraph`, `GraphrsGraph`)
  expose identical Python interface: 30 graph algorithms + bulk loaders + CRUD
- `bulk_create_nodes` / `bulk_create_relationships` confirmed on all 4 backends

#### Local Housekeeping
- Archived `nxcypher-networkit` local working copy to `_archived/nxcypher-networkit-2026-02-17`

---

## [0.2.6] - 2026-02-17

### Changed

#### Crate Renamed: `nxcypher` → `ocg`
- `Cargo.toml` `package.name` is now `ocg` — matching the PyPI package name
- All `use nxcypher::` imports updated to `use ocg::` across all test and binary files
- `Cargo.toml` and `pyproject.toml` repository URLs updated to `github.ibm.com/enjoycode/ocg`

#### Documentation Restructured
- 130+ dev session analysis docs moved to `docs/archive/`
- Root directory now contains only the 10 essential documents:
  README, CHANGELOG, LATEST_FEATURES, OPS_GUIDE, DISTRIBUTED_STORAGE_RESEARCH,
  CONTRIBUTING, CODE_OF_CONDUCT, BACKEND_SELECTION_GUIDE, BENCHMARK_RESULTS,
  COMPREHENSIVE_QUALITY_PLAN

#### CI Hardened
- Added `audit` job to `.github/workflows/wheels.yml` using `rustsec/audit-check`
- Security audit now runs before wheel builds; known CVEs fail the pipeline immediately

#### Operator Panic Safety
- Replaced all 12 `.unwrap()` calls in `operator/src/controller/*.rs` and `operator/src/metrics/mod.rs`
  with `.expect("descriptive message")` for actionable panic output in production

#### Dependency Lock Updated
- `cargo update -p k8s-openapi -p kube` — lock file now resolves k8s-openapi 0.27 and kube 3.x
  as declared in `operator/Cargo.toml` (was previously stale at 0.22.0 / 0.91)

### Fixed
- `src/lib.rs` doc comment stats updated: 3,859/3,897 scenarios, 40+ algorithms

---

## [0.2.5] - 2026-02-17

### Changed

#### Kubernetes Operator — Dependency Upgrades
- `kube` 0.91 → 3.0 (Kubernetes 1.35 API, Rust 2024 edition)
- `k8s-openapi` 0.22 (v1_29) → 0.27 (v1_33)
- `schemars` 0.8 → 1.x
- `axum` 0.7 → 0.8
- `prometheus-client` 0.22 → 0.24
- Added `jiff` 0.2 — replaces `chrono` for Kubernetes timestamp handling

#### Operator Breaking-Change Fixes
- `controller/recovery.rs`: `k8s_openapi::chrono::Utc` → `jiff::Timestamp::now()`
- `controller/mod.rs`: same `chrono` → `jiff` migration
- `controller/statefulset.rs`: `StatefulSetSpec::service_name` `String` → `Option<String>`; `ConfigMapEnvSource::name` `Option<String>` → `String` (k8s-openapi 0.27)

### Fixed

#### Operator
- Eliminated hot reconcile loop — controller no longer re-queues unnecessarily when status is already correct

---

## [0.2.0] - 2026-02-17

### Added

#### Multi-Backend Python Interface
- **`NetworKitGraph`** Python class — wraps `NetworKitRustBackend` with full algorithm suite
- **`RustworkxGraph`** Python class — wraps `RustworkxCoreBackend` with full algorithm suite
- **`GraphrsGraph`** Python class — wraps `GraphrsBackend` with full algorithm suite
- All four backends (`Graph`, `NetworKitGraph`, `RustworkxGraph`, `GraphrsGraph`) now exported from `ocg`
- All backends share identical Python interface: `execute()`, `create_node()`, `create_relationship()`, and 30+ algorithm methods
- `native_algorithms.rs` — native algorithm dispatch for `NetworKitRustBackend` (degree, betweenness, closeness, PageRank, BFS, Dijkstra, Bellman-Ford, MST, DAG, community detection, components, coloring, matching, max-flow)
- Backend smoke test suite: 162 parametrized tests covering all four backends (204 total)

#### Python Runtime
- **Native Python 3.14 support** — no longer requires `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1`
- `pyrightconfig.json` — Pyright type-checking configuration for Python 3.14

#### Infrastructure
- `operator/Dockerfile` — multi-stage Rust build for `ocg-operator` binary (v0.2.0)
- `.dockerignore` — excludes TCK suite, build artifacts, and Python env from Docker context

### Changed

#### PyO3 0.22 → 0.28 Upgrade
- Migrated all Python bindings to PyO3 0.28 API:
  - `PyObject` → `Py<PyAny>` throughout
  - `PyDict::new_bound(py)` → `PyDict::new(py)`
  - `PyList::empty_bound(py)` → `PyList::empty(py)`
  - `.to_object(py)` → `.into_any().unbind()` (for `Bound`) or `.into_pyobject(py)?.into_any().unbind()` (for primitives)
  - `bool` conversion uses `BoundObject` trait for `Borrowed<PyBool>` singleton handling
- Removed `multiple-pymethods` feature flag — consolidated all `#[pymethods]` into single blocks to fix silent method loss on macOS arm64
- `NetworKitRustBackend` fields `graph`, `nk_to_stable`, `node_id_map`, `node_properties` promoted to `pub(crate)` for native algorithm access

### Dependencies
- **PyO3** 0.22 → **0.28**

## [0.1.0] - 2026-02-16

### Added

#### Core Features
- Initial public release of OCG (OpenCypher Graph)
- **99.0% openCypher TCK compliance** (3,851/3,874 scenarios)
- Python bindings via PyO3 with full type conversion
- Multi-platform wheel distribution (65+ wheels per release)
- Support for Python 3.8-3.13+ via ABI3 forward compatibility

#### Graph Backends
- **PropertyGraph** (petgraph-based) - Default backend, production-ready
- **NetworKitRust** - High-performance analytics backend (3.4x faster traversal)
- **RustworkxCore** - Enterprise algorithm library (40+ algorithms)
- **Graphrs** - Community detection and clustering

#### Platform Support
- **Linux (glibc 2.28+)**: x86_64, i686, aarch64, armv7, **s390x (IBM Z)**, ppc64le
- **Linux (musl)**: x86_64, aarch64
- **macOS 11+**: x86_64 (Intel), arm64 (Apple Silicon)
- **Windows 10+**: x86_64, i686, arm64

#### openCypher Query Support
- Pattern matching: `MATCH`, `OPTIONAL MATCH`
- Graph updates: `CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`
- Aggregations: `count`, `sum`, `avg`, `min`, `max`, `collect`, `percentileDisc`, `percentileCont`
- Variable-length paths: `*1..n`, `*..n`, `*n..`
- Subqueries: `CALL { ... }`
- List comprehensions: `[x IN list | x.prop]`
- CASE expressions: `CASE WHEN ... THEN ... END`
- Pattern predicates: `EXISTS`, `ALL`, `ANY`, `NONE`, `SINGLE`

#### Functions
- **String functions**: `toString`, `toInteger`, `toFloat`, `toBoolean`, `substring`, `trim`, `upper`, `lower`, `replace`, `split`, `reverse`
- **Math functions**: `abs`, `ceil`, `floor`, `round`, `sign`, `sqrt`, `exp`, `log`, `log10`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`
- **Temporal functions**: `date`, `time`, `datetime`, `localdatetime`, `localtime`, `duration`
- **List functions**: `size`, `head`, `tail`, `last`, `range`, `reduce`
- **Aggregation functions**: `count`, `sum`, `avg`, `min`, `max`, `collect`, `stDev`, `stDevP`

#### Temporal Data Types
- `Date` - Calendar date (year, month, day)
- `Time` - Time of day with timezone
- `LocalTime` - Time of day without timezone
- `DateTime` - Date and time with timezone
- `LocalDateTime` - Date and time without timezone
- `Duration` - Time-based or date-based duration
- Extended temporal types for dates beyond standard ranges

#### Stored Procedures System
- **db.*** namespace: Database introspection
  - `db.labels()` - List all node labels
  - `db.relationshipTypes()` - List all relationship types
  - `db.propertyKeys()` - List all property keys
  - `db.schema.nodeTypeProperties()` - Node schema information
  - `db.schema.relTypeProperties()` - Relationship schema information
- **dbms.*** namespace: System procedures
  - `dbms.components()` - System components information
  - `dbms.procedures()` - List all available procedures

#### Documentation
- Complete Python TCK testing infrastructure (behave framework)
- Multi-platform wheel building guide (GitHub Actions)
- Docker multi-platform guide (arm64/amd64)
- PyPI publishing automation
- 4,300+ lines of comprehensive documentation

### Features

#### Performance
- Zero-copy query execution where possible
- In-memory property graph storage
- Efficient pattern matching with indexed lookups
- Backend-specific optimizations (NetworKitRust: 3.4x faster traversal)

#### Type Safety
- Type-safe Rust implementation
- Memory-safe (minimal unsafe code, only in validated contexts)
- Compile-time guarantees for graph operations
- Strong type checking in query execution

#### Error Handling
- Comprehensive error messages with context
- Detailed syntax error reporting
- Type mismatch detection
- Runtime error recovery

### Platform Distribution

#### Wheels Built Automatically
- 13 platform/architecture combinations
- 5+ Python versions (3.8, 3.9, 3.10, 3.11, 3.12+)
- Total: 65+ wheels per release
- Automatic platform detection and installation

#### Supported Architectures
- x86_64 (Intel/AMD 64-bit) - Tier 1
- aarch64 (ARM 64-bit) - Tier 1/2
- armv7 (ARM 32-bit) - Tier 2
- s390x (IBM Z/LinuxONE) - Tier 2
- ppc64le (PowerPC 64-bit LE) - Tier 2
- i686 (Intel/AMD 32-bit) - Tier 2

#### CI/CD
- Full GitHub Actions workflow
- Multi-platform builds
- Automated testing on all platforms
- Automatic PyPI publishing on tags
- GitHub Release creation with artifacts

### Dependencies
- **petgraph** 0.8 - Graph data structures
- **PyO3** 0.22 - Python bindings
- **cucumber** 0.21 - TCK test framework
- **thiserror** 2.0 - Error handling
- **chrono** 0.4 - Date/time operations
- All dependencies: Apache-2.0 or MIT licensed

### Known Limitations
- 23 TCK scenarios skipped (0.6% of suite):
  - 8 scenarios: Variable-length paths with property filters
  - 7 scenarios: OPTIONAL MATCH edge cases
  - 5 scenarios: Complex aggregation patterns
  - 3 scenarios: Unicode identifier edge cases
- No persistent storage (in-memory only)
- No index support yet
- No constraint support yet
- No transaction support (auto-commit only)

### Breaking Changes
- N/A (initial release)

### Security
- Apache License 2.0
- All dependencies verified for compatible licenses
- No known security vulnerabilities
- Memory-safe Rust implementation

---

## [0.2.0] - 2026-02-17

### Added

#### Bulk Loader API (`6c4179d`)
- New bulk loading methods on `Graph`: `bulk_create_nodes()`, `bulk_create_relationships()`
- Also exposes direct single-node/edge methods: `create_node()`, `create_relationship()`
- Accepts batched node/edge lists in a single call — **57.5x faster** than
  repeated OpenCypher `CREATE` for large graphs (100 nodes: 79 ms → 1.38 ms)

#### Universal Algorithm Library — NetworKit Backend (`a6e091b`)
- 40+ algorithms ported directly from source to the NetworKit `Graph` struct
  with zero intermediate format conversions:
  - **Pathfinding**: A\*, Bellman-Ford, Floyd-Warshall, all-pairs Dijkstra,
    negative-cycle detection
  - **Spanning trees**: Kruskal MST/MaxST, Prim MST
  - **DAG**: topological sort (Kahn + DFS), `is_dag`, cycle detection,
    longest path, transitive closure
  - **Flow**: Edmonds-Karp max-flow, min-cut
  - **Coloring**: greedy node/edge coloring, chromatic number approximation
  - **Matching**: max-weight matching, max-cardinality matching
  - **Community detection**: Louvain, Label Propagation, Girvan-Newman,
    modularity scoring

#### `PetgraphAlgorithms` Trait — Universal Backend Coverage (`702568c`)
- New `src/graph/backends/petgraph_algorithms.rs` with a shared trait that
  provides all 40+ algorithms to every petgraph-backed backend via a single
  `StableDiGraph → NetworKit` conversion layer
- All four backends now have the full algorithm surface:
  - `NetworKitRustBackend` — native (no conversion overhead)
  - `RustworkxCoreBackend` — via `PetgraphAlgorithms`
  - `GraphrsBackend` — via `PetgraphAlgorithms` + Louvain/Leiden community detection
  - `PropertyGraph` — via `PetgraphAlgorithms`

#### Python Algorithm Bindings (`98625bf`)
- 30+ algorithm methods exposed directly on `Graph` (Python class)
- Centrality, pathfinding (incl. A\* with Python heuristic), spanning trees,
  DAG, flow, coloring, matching, community detection, components
- 42 integration tests in `tests/test_algorithms.py`, all passing

#### Distributed Architecture (`--features distributed`)
- **Partition-aware IDs**: Composite u64 (partition_id 16-bit | local_id 48-bit)
- **Partitioning algorithms**: `HashPartitioner`, `RangePartitioner`, pluggable `GraphPartitioner` trait
- **PartitionedGraphBackend**: Full `GraphBackend` trait with cross-partition edge tracking
- **Parquet serialization**: ZSTD level-3, S3/object-storage first via `object_store`
- **Arrow Flight RPC (v57/tonic 0.14)**: Zero-copy node/edge streaming
- **etcd metadata service**: `PartitionLocationService` — register, heartbeat, status, refresh cache
- **Heartbeat & failure detection**: 5s interval emitter + 30s timeout detector
- **Recovery manager**: `LeastLoadedSelector`, `StatefulOrdinalSelector`
- **Pod startup**: `PodConfig::from_env()`, `PodStartup::run()`, `partition_node` binary
- **Dynamic rebalancing**: `MetricsCollector`, `Rebalancer` — Split/Merge/Migrate actions
- **Query routing**: `PartitionAnalyzer`, `QueryRouter`
- **Kubernetes operator** (`operator/` crate): Levels 1–5 (Install, Upgrade, Backup, Observability, Auto-Pilot)
  - Level 1: StatefulSet, ConfigMap, Services
  - Level 2: Image-drift detection + rollback
  - Level 3: CronJob backup + Degraded event recovery
  - Level 4: Prometheus metrics via axum `/metrics`
  - Level 5: HPA + PDB + rebalance trigger

### Changed
- `Cargo.toml`: Added `distributed` feature + `[workspace]` with `operator` member
- `src/error.rs`: Added `ExecutionError::PartitionMismatch(String)`
- `src/graph/storage.rs`: Added `add_existing_node()` and `create_relationship_with_id()`

### Tests
- Rust lib tests: **276** passing (up from 236 at v0.1.8)
- Distributed unit tests: 82 passing (6 live-server tests marked `#[ignore]`)
- Python integration tests: 42 passing

### Planned for 0.2.0
- Add OpenCypher `algo.*` stored procedures
- Fix remaining TCK edge cases → maintain 100% compliance
- Add proper index support
- Flight `LoadPartition` action wiring (Phase 9 production completion)
- Tunable consistency levels (STRONG, QUORUM, EVENTUAL)
- S3 secret injection in StatefulSet (`envFrom.secretRef`)

### Planned for 1.0.0
- Constraint support (UNIQUE, EXISTS, NODE KEY)
- Transaction support (BEGIN, COMMIT, ROLLBACK)
- Multi-replica partitions for fault tolerance (3× replication)
- Production-ready stability guarantees
- Comprehensive performance optimization

---

## [0.1.8] - 2026-02-15

### Added
- 100% openCypher TCK compliance (3,874/3,874 scenarios)
- Multi-platform wheel CI for github.com and github.ibm.com
- PyPI publishing via API token

---

[0.1.0]: https://github.ibm.com/enjoycode/ocg-persistent/releases/tag/v0.1.0
[0.1.8]: https://github.ibm.com/enjoycode/ocg-persistent/releases/tag/v0.1.8
[0.2.7]: https://github.ibm.com/enjoycode/ocg/compare/v0.2.6...v0.2.7
[0.2.6]: https://github.ibm.com/enjoycode/ocg/compare/v0.2.5...v0.2.6
[0.2.5]: https://github.ibm.com/enjoycode/ocg/compare/v0.2.0...v0.2.5
[0.2.0]: https://github.ibm.com/enjoycode/ocg-persistent/compare/v0.1.8...v0.2.0
