graphforge 0.3.4__tar.gz → 0.3.6__tar.gz

{graphforge-0.3.4 → graphforge-0.3.6}/.codecov.yml

@@ -23,7 +23,7 @@ coverage:
   range: "70...95"                     # Coverage range (red to green)
 
 comment:
-  layout: "header, diff, flags, components, footer"
+  layout: "header, diff, flags, components, footer, tests"
   behavior: default                    # Comment on every PR
   require_changes: false               # Always comment, even if no changes
 
@@ -32,6 +32,8 @@ flags:
     paths:
       - src/
     carryforward: true                 # Use previous coverage if job fails
+  tck-compliance:
+    carryforward: true                 # Show previous TCK results if job skipped
 
 component_management:
   individual_components:

{graphforge-0.3.4 → graphforge-0.3.6}/.github/workflows/test.yml

@@ -124,6 +124,51 @@ jobs:
       - name: Run bandit security scanner
         run: uv run bandit -c pyproject.toml -r src/
 
+  tck-regression:
+    name: TCK OpenCypher Compliance
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run TCK tests (parallel)
+        id: tck_tests
+        continue-on-error: true
+        run: uv run pytest tests/tck/ -n auto -v --junitxml=test-results-tck.xml
+
+      - name: Report TCK compliance metrics
+        if: always()
+        run: uv run python3 scripts/tck_metrics.py test-results-tck.xml
+
+      - name: Upload TCK results to Codecov
+        uses: codecov/codecov-action@v5
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: test-results-tck.xml
+          flags: tck-compliance
+          report_type: test_results
+          fail_ci_if_error: false
+
+      - name: Upload TCK results artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: tck-test-results
+          path: test-results-tck.xml
+
   coverage:
     name: Coverage Report
     runs-on: ubuntu-latest

{graphforge-0.3.4 → graphforge-0.3.6}/CHANGELOG.md

@@ -5,6 +5,64 @@ 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.6] - 2026-02-28
+
+### Fixed - TCK Harness Correctness
+- **Integer property comparison** (#252) — TCK harness was comparing integer properties as strings, causing ~423 false failures; now coerced correctly
+- **Map literal value coercion** (#261) — `_parse_map_literal` in conftest now coerces numeric string values, fixing ~30 false failures
+
+### Fixed - Temporal Correctness
+- **`date({})` / `datetime({})` / `time({})` map constructors** (#253, #268) — component validation, UTC defaults, and function-as-argument parsing
+- **`UnexpectedEOF` on duration/datetime literals** (#254) — parser now handles all ISO 8601 duration and datetime forms
+- **Timezone offset `+HH:MM` parsing** (#255) — `+HH:MM` and `-HH:MM` offsets now parsed correctly
+- **Date map constructor component validation** (#256) — out-of-range components raise `ValueError`
+- **`datetime(string)` defaults to UTC** (#276) — string datetimes without timezone now default to UTC per spec
+- **Map constructor omitted components default to 1** (#278) — `date({year: 2015})` → `2015-01-01`, not error
+- **`TRUNCATE` units: week, weekYear, quarter, decade, century, millennium** (#269) — all truncation units now return correct values
+- **Week-based and select-form datetime constructors** (#270) — `datetime({week: 30, ...})` and similar forms return correct values
+- **Duration serialization, comparison, multiplication, and fractional arithmetic** (#271) — full duration correctness including `duration.between()`
+- **`datetime(aDatetime)` type coercion** (#274) — coercing datetime subtypes no longer conflicts with `:E` label parser token
+- **Compact ISO 8601 date/datetime string formats** (#273) — ordinal (`YYYY-DDD`, `YYYYDDD`), week date (`YYYY-Www[-D]`), year-month (`YYYY-MM`, `YYYYMM`), and year-only (`YYYY`) all parsed correctly
+- **IANA timezone names** (#272) — `[Region/City]` suffix in datetime strings is parsed; IANA zone is authoritative over explicit offset; historical second-precision offsets (e.g. `+00:53:28`) handled correctly
+
+### TCK Coverage
+- **2,507 passing** (up from ~1,694 at v0.3.5) — +813 net new passing scenarios
+- Theme: all temporal TCK scenarios now pass; harness accuracy fully corrected
+
+## [0.3.5] - 2026-02-19
+
+### Added - Math Functions (#195, #196, #197)
+- **sqrt(x)** - Square root function
+  - Returns `CypherFloat`; negative input returns `null`; null propagation
+  - Example: `RETURN sqrt(4) AS r` → `2.0`
+- **rand()** - Random float in [0.0, 1.0)
+  - Takes no arguments; returns a new `CypherFloat` each call
+  - Example: `RETURN rand() * 100 AS r`
+- **pow(base, exponent)** - Exponentiation function
+  - Consistent with `^` operator: `pow(2, 3) = 2^3 = 8`
+  - Null propagation for both arguments
+  - Example: `RETURN pow(2, 10) AS r` → `1024`
+
+### Fixed - Aggregation Function Tests (#201, #202, #203, #204)
+- Fixed ~24 syntax bugs (`RETURNfunc(` → `RETURN func(`) in aggregation test files
+- `percentileDisc()`, `percentileCont()`, `stDev()`, `stDevP()` were already implemented; tests now pass
+- Updated docs to reflect all four as COMPLETE
+
+### Added - TCK Step Definitions (#237)
+- Added 5 missing pytest-bdd step definitions unblocking ~129 previously failing TCK scenarios:
+  - `executing control query:` — alias for `executing query:`
+  - `the result should be (ignoring element order for lists):` — row comparison with sorted list values
+  - `the result should be, in order (ignoring element order for lists):` — ordered variant
+  - `parameters are:` — parses datatable, substitutes `$param` references in queries
+  - `there exists a procedure` — marked `xfail` (CALL procedures tracked for v0.3.6 in #190)
+- Extended `_parse_value()` to handle list literals like `['Foo', 'Bar']`
+- Extended `_row_to_comparable()` to handle `CypherList` values
+
+### Implementation Status Updates
+- Math functions: `sqrt`, `rand`, `pow` now COMPLETE (was NOT_IMPLEMENTED)
+- Aggregation functions: `percentileDisc`, `percentileCont`, `stDev`, `stDevP` now COMPLETE
+- TCK pass rate: +129 passing scenarios, +50 xfailed (procedure CALL)
+
 ## [0.3.4] - 2026-02-18
 
 ### Added - Power Arithmetic Operator (#213)

{graphforge-0.3.4 → graphforge-0.3.6}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help lint format type-check security test pre-push clean
+.PHONY: help lint format type-check security test pre-push clean test-tck docstring-coverage test-network
 
 help:  ## Show this help message
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
@@ -18,24 +18,31 @@ type-check:  ## Run mypy type checker
 security:  ## Run Bandit security scanner
 	uv run bandit -c pyproject.toml -r src/
 
-test:  ## Run all tests
-	uv run pytest tests/
+docstring-coverage:  ## Check docstring coverage (90% minimum)
+	uv run interrogate src/graphforge --fail-under 90 --quiet
 
-test-unit:  ## Run unit tests only
-	uv run pytest tests/unit -v
+test:  ## Run all tests in parallel (excludes snap/network downloads)
+	uv run pytest tests/ -n auto -m "not snap"
 
-test-integration:  ## Run integration tests only
-	uv run pytest tests/integration -v
+test-unit:  ## Run unit tests in parallel
+	uv run pytest tests/unit -n auto
+
+test-integration:  ## Run integration tests in parallel (excludes snap/network downloads)
+	uv run pytest tests/integration -n auto -m "not snap"
+
+test-network:  ## Run external network/download tests (snap datasets; requires internet)
+	uv run pytest tests/ -m "snap" -v
+
+test-tck:  ## Run TCK compliance tests in parallel
+	uv run pytest tests/tck/ -n auto -v
 
 coverage:  ## Run tests with coverage measurement
 	@echo "Running tests with coverage..."
-	uv run pytest tests/unit tests/integration \
+	uv run pytest tests/unit tests/integration -m "not snap" \
 		--cov=src \
 		--cov-branch \
 		--cov-report=term-missing \
-		--cov-report=xml \
-		--cov-report=html \
-		-n auto
+		--cov-report=xml
 
 test-analytics:  ## Run tests with analytics output (JUnit XML)
 	@echo "Running tests with analytics output..."
@@ -55,7 +62,9 @@ coverage-strict:  ## Strict 90% coverage check for new features
 		(echo "❌ Coverage below 90% - consider adding more tests" && exit 1)
 	@echo "✅ Coverage meets strict threshold"
 
-coverage-report:  ## Open HTML coverage report in browser
+coverage-report:  ## Generate HTML coverage report and open in browser
+	@echo "Generating HTML coverage report..."
+	uv run coverage html
 	@echo "Opening coverage report in browser..."
 	@open htmlcov/index.html || xdg-open htmlcov/index.html || \
 		echo "Coverage report generated at htmlcov/index.html"
@@ -86,7 +95,7 @@ check-patch-coverage:  ## Validate patch coverage for changed files (90% thresho
 		echo "✅ Patch coverage meets 90% threshold"; \
 	fi
 
-pre-push: format-check lint type-check security coverage check-coverage check-patch-coverage  ## Run all pre-push checks (mirrors CI)
+pre-push: format-check lint type-check security docstring-coverage coverage check-coverage check-patch-coverage  ## Run all pre-push checks (mirrors CI)
 	@echo "✅ All pre-push checks passed!"
 
 clean:  ## Clean up cache files

{graphforge-0.3.4 → graphforge-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphforge
-Version: 0.3.4
+Version: 0.3.6
 Summary: Composable graph tooling for analysis, construction, and refinement
 Project-URL: Homepage, https://github.com/DecisionNerd/graphforge
 Project-URL: Repository, https://github.com/DecisionNerd/graphforge
@@ -98,25 +98,23 @@ Modern data science and ML workflows increasingly produce **graph-shaped data**
 > *We are not building a database for applications.*
 > *We are building a graph execution environment for thinking.*
 
-### Latest Release: v0.3.4
+### Latest Release: v0.3.6
 
-Version 0.3.4 completes operator and string function enhancements:
+Version 0.3.6 is a correctness release — all temporal TCK scenarios now pass and the TCK harness is fully accurate:
 
-- **String functions**: `toUpper()`, `toLower()` camelCase variants - Aliases for existing UPPER/LOWER functions
-- **Logical operators**: `XOR` - Exclusive OR with proper precedence (NOT > AND > XOR > OR) and NULL handling
-- **Arithmetic operators**: `^` (power/exponentiation) - Right-associative with full numeric support (negative and fractional exponents)
-- **List operations**: List slicing `[start..end]` and negative indexing `list[-1]` (already implemented, now documented)
-- **Comprehensive testing**: 79 new integration tests (18 string, 22 XOR, 39 power)
-- **Operator completion**: List operators 100% (5/5), Overall operators 94% (32/34, up from 88%)
-- **Function progress**: 56/72 functions (78%, up from 76%)
+- **Temporal correctness**: compact ISO 8601 formats, IANA timezone names, `TRUNCATE` units, duration arithmetic, map constructors — all fixed
+- **TCK harness**: integer/map literal coercion bugs fixed, eliminating ~450 false failures
+- **+813 net new passing TCK scenarios**: 2,507 passing (up from 1,694 at v0.3.5)
 
 **Previous Releases**:
+- **v0.3.5**: `sqrt()`, `rand()`, `pow()`, aggregation function fixes, 5 TCK step definitions (+129 scenarios)
+- **v0.3.4**: `toUpper()`/`toLower()` aliases, `XOR` operator, `^` power operator, list slicing docs
 - **v0.3.3**: Pattern comprehensions, CALL subqueries, Pattern predicates
 - **v0.3.2**: List operations (`filter()`, `extract()`, `reduce()`)
 - **v0.3.1**: Quantifier functions (`all()`, `any()`, `none()`, `single()`), `exists()`, `isEmpty()`
 - **v0.3.0**: OPTIONAL MATCH, UNION, List comprehensions, EXISTS/COUNT subqueries, Variable-length paths, 109+ datasets
 
-**TCK Coverage**: ~38% openCypher compatibility
+**TCK Coverage**: ~64% of collected scenarios passing (2,507 / 3,885)
 
 See [CHANGELOG.md](CHANGELOG.md) for complete release notes.
 
@@ -1415,7 +1413,9 @@ GraphForge implements a **practical subset of OpenCypher** focused on common gra
 
 **Functions:**
 - String: length, substring, toUpper/toLower (both camelCase and UPPERCASE variants), trim, reverse, split, replace, left, right, ltrim, rtrim
+- Math: abs, ceil, floor, round, sign, sqrt, rand, pow
 - Type conversion: toInteger, toFloat, toString, toBoolean
+- Aggregation: count, sum, avg, min, max, collect, percentileDisc, percentileCont, stDev, stDevP
 - Spatial: point, distance
 - Temporal: date, datetime, time, duration
 - Graph: id, labels, type
@@ -1460,6 +1460,7 @@ GraphForge tracks compliance using the openCypher Technology Compatibility Kit (
 | v0.1.4 | 1,277/7,722 | 16.5% |
 | v0.2.0 | ~1,900/7,722 | ~25% |
 | v0.3.0 | ~3,000/7,722 | ~39% |
+| v0.3.5 | 1,694/3,885 collected | ~44% collected |
 | v0.4.0 (target) | ~4,250/7,722 | ~55% |
 | v0.5.0 (target) | ~5,400/7,722 | ~70% |
 | v0.6.0 (target) | ~6,300/7,722 | ~82% |

{graphforge-0.3.4 → graphforge-0.3.6}/README.md

@@ -52,25 +52,23 @@ Modern data science and ML workflows increasingly produce **graph-shaped data**
 > *We are not building a database for applications.*
 > *We are building a graph execution environment for thinking.*
 
-### Latest Release: v0.3.4
+### Latest Release: v0.3.6
 
-Version 0.3.4 completes operator and string function enhancements:
+Version 0.3.6 is a correctness release — all temporal TCK scenarios now pass and the TCK harness is fully accurate:
 
-- **String functions**: `toUpper()`, `toLower()` camelCase variants - Aliases for existing UPPER/LOWER functions
-- **Logical operators**: `XOR` - Exclusive OR with proper precedence (NOT > AND > XOR > OR) and NULL handling
-- **Arithmetic operators**: `^` (power/exponentiation) - Right-associative with full numeric support (negative and fractional exponents)
-- **List operations**: List slicing `[start..end]` and negative indexing `list[-1]` (already implemented, now documented)
-- **Comprehensive testing**: 79 new integration tests (18 string, 22 XOR, 39 power)
-- **Operator completion**: List operators 100% (5/5), Overall operators 94% (32/34, up from 88%)
-- **Function progress**: 56/72 functions (78%, up from 76%)
+- **Temporal correctness**: compact ISO 8601 formats, IANA timezone names, `TRUNCATE` units, duration arithmetic, map constructors — all fixed
+- **TCK harness**: integer/map literal coercion bugs fixed, eliminating ~450 false failures
+- **+813 net new passing TCK scenarios**: 2,507 passing (up from 1,694 at v0.3.5)
 
 **Previous Releases**:
+- **v0.3.5**: `sqrt()`, `rand()`, `pow()`, aggregation function fixes, 5 TCK step definitions (+129 scenarios)
+- **v0.3.4**: `toUpper()`/`toLower()` aliases, `XOR` operator, `^` power operator, list slicing docs
 - **v0.3.3**: Pattern comprehensions, CALL subqueries, Pattern predicates
 - **v0.3.2**: List operations (`filter()`, `extract()`, `reduce()`)
 - **v0.3.1**: Quantifier functions (`all()`, `any()`, `none()`, `single()`), `exists()`, `isEmpty()`
 - **v0.3.0**: OPTIONAL MATCH, UNION, List comprehensions, EXISTS/COUNT subqueries, Variable-length paths, 109+ datasets
 
-**TCK Coverage**: ~38% openCypher compatibility
+**TCK Coverage**: ~64% of collected scenarios passing (2,507 / 3,885)
 
 See [CHANGELOG.md](CHANGELOG.md) for complete release notes.
 
@@ -1369,7 +1367,9 @@ GraphForge implements a **practical subset of OpenCypher** focused on common gra
 
 **Functions:**
 - String: length, substring, toUpper/toLower (both camelCase and UPPERCASE variants), trim, reverse, split, replace, left, right, ltrim, rtrim
+- Math: abs, ceil, floor, round, sign, sqrt, rand, pow
 - Type conversion: toInteger, toFloat, toString, toBoolean
+- Aggregation: count, sum, avg, min, max, collect, percentileDisc, percentileCont, stDev, stDevP
 - Spatial: point, distance
 - Temporal: date, datetime, time, duration
 - Graph: id, labels, type
@@ -1414,6 +1414,7 @@ GraphForge tracks compliance using the openCypher Technology Compatibility Kit (
 | v0.1.4 | 1,277/7,722 | 16.5% |
 | v0.2.0 | ~1,900/7,722 | ~25% |
 | v0.3.0 | ~3,000/7,722 | ~39% |
+| v0.3.5 | 1,694/3,885 collected | ~44% collected |
 | v0.4.0 (target) | ~4,250/7,722 | ~55% |
 | v0.5.0 (target) | ~5,400/7,722 | ~70% |
 | v0.6.0 (target) | ~6,300/7,722 | ~82% |

{graphforge-0.3.4 → graphforge-0.3.6}/docs/development/contributing.md

@@ -59,6 +59,8 @@ make test
 # Run specific categories
 make test-unit           # Fast unit tests only
 make test-integration    # Integration tests only
+make test-tck            # TCK compliance tests
+make test-tck-parallel   # TCK tests in parallel (faster, uses all CPU cores)
 
 # Run with coverage reporting
 make coverage            # Run tests + generate coverage reports

{graphforge-0.3.4 → graphforge-0.3.6}/docs/development/testing.md

@@ -346,6 +346,9 @@ pytest tests/unit/test_data_model.py::test_node_ref_equality
 # Run in parallel (with pytest-xdist)
 pytest -n auto
 
+# Run TCK tests in parallel (recommended for large TCK suite)
+make test-tck-parallel   # or: pytest tests/tck/ -n auto
+
 # Run with verbose output
 pytest -vv
 
@@ -621,6 +624,71 @@ pip install -e ".[dev]"
 
 ---
 
+## Known Issues & Investigated Solutions
+
+### pytest-xdist + pytest-cov deadlock on macOS / Python 3.13
+
+**Symptom:** `make pre-push` (or any `pytest -n auto --cov=...` invocation) hangs
+indefinitely at the very end of the test run. Progress reaches ~100% then freezes.
+CPU drops to 0%. Only `kill` escapes it.
+
+**Root cause:** `pytest-cov` collects coverage data from xdist workers via IPC
+(inter-process communication sockets). When workers finish and close their sockets,
+a coverage data-collection thread in the main process is still blocked on `read()`.
+The main thread waits for that lock → deadlock. Confirmed via `sample <PID>`:
+```
+main thread: lock_PyThread_acquire_lock → _PyMutex_LockTimed → _PySemaphore_Wait
+worker thread: read() (44020 calls pending)
+```
+Reproduced consistently on macOS (Darwin 25.x) + Python 3.13.7 + pytest-cov 7.0.0 +
+pytest-xdist 3.x. Not observed on Linux CI.
+
+**What does NOT work:**
+
+| Attempted fix | Result |
+|---|---|
+| `--cov-report=html` alone | Still deadlocks; HTML is slow but not the cause |
+| `[tool.coverage.run] parallel = true` + `-n auto` | No deadlock but **2× slower** (3:54 vs 1:30) — per-process `.coverage.PID` file I/O overwhelms the speedup from parallelism |
+| `concurrency = ["multiprocessing", "thread"]` + `parallel = true` | Same outcome as above; requires `coverage combine` step which adds no benefit |
+
+**Solution (current `Makefile`):** Run coverage serially (no `-n auto`) and exclude
+the two other causes of slowdown:
+
+```makefile
+coverage:
+    uv run pytest tests/unit tests/integration -m "not snap" \
+        --cov=src \
+        --cov-branch \
+        --cov-report=term-missing \
+        --cov-report=xml
+```
+
+Key flags:
+- **No `-n auto`** — eliminates the IPC deadlock entirely.
+- **`-m "not snap"`** — skips SNAP network-dataset tests (they download files, run
+  alphabetically last, and are already skipped in CI per their marker description).
+- **No `--cov-report=html`** — HTML generation over ~13 k lines of source is slow;
+  use `make coverage-report` on demand instead.
+
+**Timing (Apple Silicon, Python 3.13, ~3 450 tests):**
+
+| Approach | Wall time |
+|---|---|
+| `-n auto`, no coverage (baseline) | ~91 s |
+| `-n auto` + `--cov` (original, pre-fix) | ∞ (deadlock) |
+| `-n auto` + `--cov` + `parallel=true` | ~234 s |
+| Serial `--cov`, `-m "not snap"`, no HTML (current) | ~150 s |
+
+The serial run is only ~60 s slower than the parallel baseline because coverage
+overhead is modest (~38 s) and `parallel=true` file-I/O costs more than it saves.
+
+**If this is re-investigated in the future:** the deadlock is a known upstream issue
+between pytest-cov and pytest-xdist on Python 3.13's stricter GIL/semaphore
+behaviour. Check the [pytest-cov changelog](https://pytest-cov.readthedocs.io/) for
+a fix before attempting another workaround.
+
+---
+
 ## Success Metrics
 
 The testing infrastructure is successful when:

{graphforge-0.3.4 → graphforge-0.3.6}/docs/reference/implementation-status/functions.md

@@ -14,15 +14,15 @@ Implementation status of OpenCypher built-in functions in GraphForge.
 | Category | Total Functions | Complete | Partial | Not Implemented |
 |----------|----------------|----------|---------|-----------------|
 | String | 13 | 13 (100%) | 0 (0%) | 0 (0%) |
-| Numeric | 10 | 7 (70%) | 0 (0%) | 3 (30%) |
+| Numeric | 10 | 10 (100%) | 0 (0%) | 0 (0%) |
 | List | 8 | 7 (88%) | 0 (0%) | 1 (12%) |
-| Aggregation | 10 | 5 (50%) | 0 (0%) | 5 (50%) |
+| Aggregation | 10 | 9 (90%) | 0 (0%) | 1 (10%) |
 | Predicate | 6 | 6 (100%) | 0 (0%) | 0 (0%) |
 | Scalar | 9 | 8 (89%) | 0 (0%) | 1 (11%) |
 | Temporal | 11 | 11 (100%) | 0 (0%) | 0 (0%) |
 | Spatial | 2 | 2 (100%) | 0 (0%) | 0 (0%) |
 | Path | 3 | 3 (100%) | 0 (0%) | 0 (0%) |
-| **TOTAL** | **72** | **58 (81%)** | **0 (0%)** | **14 (19%)** |
+| **TOTAL** | **72** | **65 (90%)** | **0 (0%)** | **7 (10%)** |
 
 ---
 
@@ -119,17 +119,26 @@ Implementation status of OpenCypher built-in functions in GraphForge.
 **Signatures:** `toInteger(value)`, `toFloat(value)`
 **Tests:** Type conversion scenarios
 
-### sqrt() ❌
-**Status:** NOT_IMPLEMENTED
-**Notes:** Not yet implemented. Simple addition, low difficulty.
+### sqrt() ✅
+**Status:** COMPLETE
+**File:** `evaluator.py:1672`
+**Signature:** `sqrt(number)`
+**Tests:** tests/integration/test_math_functions_extended.py (TestSqrtFunction)
+**Notes:** Returns CypherFloat. Negative input returns null.
 
-### rand() ❌
-**Status:** NOT_IMPLEMENTED
-**Notes:** Random float generation. Not yet implemented.
+### rand() ✅
+**Status:** COMPLETE
+**File:** `evaluator.py:1683`
+**Signature:** `rand()`
+**Tests:** tests/integration/test_math_functions_extended.py (TestRandFunction)
+**Notes:** Returns random CypherFloat in [0.0, 1.0).
 
-### pow() / ^ operator ❌
-**Status:** NOT_IMPLEMENTED
-**Notes:** Power/exponentiation operator not implemented.
+### pow() ✅
+**Status:** COMPLETE
+**File:** `evaluator.py:1690`
+**Signature:** `pow(base, exponent)`
+**Tests:** tests/integration/test_math_functions_extended.py (TestPowFunction)
+**Notes:** Exponentiation function, consistent with ^ operator. Returns CypherInt for int^int with non-negative exponent when result is whole.
 
 ---
 
@@ -211,13 +220,19 @@ Implementation status of OpenCypher built-in functions in GraphForge.
 **Signature:** `collect(expression)`
 **Tests:** Aggregation scenarios
 
-### percentileDisc(), percentileCont() ❌
-**Status:** NOT_IMPLEMENTED
-**Notes:** Percentile calculations. Not yet implemented.
+### percentileDisc(), percentileCont() ✅
+**Status:** COMPLETE
+**File:** `src/graphforge/executor/executor.py` (aggregation logic)
+**Signatures:** `percentileDisc(expression, percentile)`, `percentileCont(expression, percentile)`
+**Tests:** tests/unit/executor/test_aggregation_functions_advanced.py, tests/integration/test_aggregation_functions_advanced.py
+**Notes:** Discrete and continuous percentile calculations. NULL values ignored. Percentile must be between 0.0 and 1.0.
 
-### stDev(), stDevP() ❌
-**Status:** NOT_IMPLEMENTED
-**Notes:** Standard deviation calculations. Not yet implemented.
+### stDev(), stDevP() ✅
+**Status:** COMPLETE
+**File:** `src/graphforge/executor/executor.py` (aggregation logic)
+**Signatures:** `stDev(expression)`, `stDevP(expression)`
+**Tests:** tests/unit/executor/test_aggregation_functions_advanced.py, tests/integration/test_aggregation_functions_advanced.py
+**Notes:** Sample (stDev) and population (stDevP) standard deviation. NULL values ignored. stDev returns NULL for single value, stDevP returns 0.
 
 ---
 
@@ -408,20 +423,15 @@ All temporal functions are ✅ COMPLETE with comprehensive support added in v0.3
 3. **Core string/numeric/list functions**: Most commonly used functions implemented
 4. **Type conversions**: Complete conversion functions (toString, toInteger, toFloat, toBoolean)
 5. **Aggregations**: Essential aggregations (count, sum, avg, min, max, collect)
+6. **Statistical aggregations**: percentileDisc, percentileCont, stDev, stDevP (v0.3.5)
 
 ### Limitations
 
-1. **Statistical aggregations**: percentile and standard deviation functions missing
-2. **List operations**: extract(), filter(), reduce() not implemented
-3. **Mathematical functions**: sqrt(), rand(), pow() missing
+1. **List operations**: extract(), filter(), reduce() not implemented
 
 ### Recommended Priority for v0.4.0+
 
-1. **High**: sqrt() - common mathematical operation
-2. **Medium**: Statistical aggregations (percentileDisc, percentileCont, stDev)
-3. **Medium**: List operations (extract, filter, reduce)
-4. **Low**: rand() - useful but low priority
-5. **Low**: pow() - can use alternative approaches
+1. **Medium**: List operations (extract, filter, reduce)
 
 ---
 

{graphforge-0.3.4 → graphforge-0.3.6}/docs/reference/opencypher-compatibility-matrix.md

@@ -14,18 +14,18 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 | Category | Total Features | Complete | Partial | Not Implemented | TCK Scenarios | Coverage |
 |----------|---------------|----------|---------|-----------------|---------------|----------|
 | **Clauses** | 20 | 16 (80%) | 1 (5%) | 3 (15%) | ~1,180 | Good |
-| **Functions** | 72 | 53 (74%) | 0 (0%) | 19 (26%) | ~380 | Good |
+| **Functions** | 72 | 60 (83%) | 0 (0%) | 12 (17%) | ~380 | Good |
 | **Operators** | 34 | 30 (88%) | 0 (0%) | 4 (12%) | ~300 | Good |
 | **Patterns** | 8 | 6 (75%) | 1 (12%) | 1 (13%) | ~200 | Good |
-| **TOTAL** | **134** | **105 (78%)** | **2 (2%)** | **27 (20%)** | **~2,060** | **Good** |
+| **TOTAL** | **134** | **112 (84%)** | **2 (2%)** | **20 (15%)** | **~2,060** | **Good** |
 
-### Overall Compliance: **~78% Feature Complete**
+### Overall Compliance: **~84% Feature Complete**
 
 ---
 
 ## Quick Reference
 
-### ✅ Fully Supported (105 features)
+### ✅ Fully Supported (112 features)
 - Core querying: MATCH, RETURN, WHERE, ORDER BY, LIMIT, SKIP
 - Query chaining: WITH (full spec compliance)
 - Writing: CREATE, MERGE, SET, REMOVE, DELETE, DETACH DELETE
@@ -38,13 +38,11 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 - CALL { } subqueries (EXISTS/COUNT only, general syntax missing)
 - Pattern predicates (basic WHERE in patterns, needs completion)
 
-### ❌ Not Supported (27 features)
+### ❌ Not Supported (20 features)
 - CALL procedures (no procedure system)
 - Predicate functions (all, any, none, single, isEmpty)
 - List operations (extract, filter, reduce)
 - Pattern comprehension
-- Some math functions (sqrt, rand, pow)
-- Statistical aggregations (percentile, stdev)
 
 ---
 
@@ -77,7 +75,7 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 
 ---
 
-### Functions (72 total: 53 complete, 0 partial, 19 not implemented)
+### Functions (72 total: 60 complete, 0 partial, 12 not implemented)
 
 #### String Functions (13 total: 11 complete, 2 not implemented)
 
@@ -94,7 +92,7 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 | length() | ❌ Not Implemented | 1 | N/A | Conflicts with path length() |
 | toUpper/toLower (camelCase) | ❌ Not Implemented | 2 | N/A | Only UPPER/LOWER aliases |
 
-#### Numeric Functions (10 total: 7 complete, 3 not implemented)
+#### Numeric Functions (10 total: 10 complete) ✅ COMPLETE CATEGORY
 
 | Function | Status | TCK Scenarios | File | Notes |
 |----------|--------|---------------|------|-------|
@@ -103,9 +101,9 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 | round() | ✅ Complete | 1 | evaluator.py:1369 | With precision |
 | sign() | ✅ Complete | 1 | evaluator.py:1409 | Sign of number |
 | toInteger(), toFloat() | ✅ Complete | 2 | evaluator.py:1556, 1600 | Type conversion |
-| sqrt() | ❌ Not Implemented | 0 | N/A | Square root |
-| rand() | ❌ Not Implemented | 0 | N/A | Random number |
-| pow() / ^ | ❌ Not Implemented | 0 | N/A | Power operator |
+| sqrt() | ✅ Complete | 7 | evaluator.py:1672 | Square root (v0.3.5) |
+| rand() | ✅ Complete | 4 | evaluator.py:1683 | Random number (v0.3.5) |
+| pow() | ✅ Complete | 9 | evaluator.py:1690 | Power function (v0.3.5) |
 
 #### List Functions (8 total: 6 complete, 2 not implemented)
 
@@ -120,7 +118,7 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 | filter() | ❌ Not Implemented | 10 | N/A | List filtering |
 | reduce() | ❌ Not Implemented | 5 | N/A | List reduction |
 
-#### Aggregation Functions (10 total: 5 complete, 5 not implemented)
+#### Aggregation Functions (10 total: 9 complete, 1 not implemented)
 
 | Function | Status | TCK Scenarios | File | Notes |
 |----------|--------|---------------|------|-------|
@@ -129,8 +127,8 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
 | avg() | ✅ Complete | 3 | executor.py | Average |
 | min(), max() | ✅ Complete | 5 | executor.py | Min/max values |
 | collect() | ✅ Complete | 4 | executor.py | Collect to list |
-| percentileDisc(), percentileCont() | ❌ Not Implemented | 2 | N/A | Percentiles |
-| stDev(), stDevP() | ❌ Not Implemented | 1 | N/A | Standard deviation |
+| percentileDisc(), percentileCont() | ✅ Complete | 2 | executor.py | Percentiles (v0.3.5) |
+| stDev(), stDevP() | ✅ Complete | 1 | executor.py | Standard deviation (v0.3.5) |
 
 #### Predicate Functions (6 total: 0 complete, 6 not implemented) ⚠️ HIGH PRIORITY
 
@@ -491,10 +489,6 @@ Comprehensive status matrix for GraphForge's OpenCypher implementation, showing
    - Complex feature
    - 15 TCK scenarios failing
 
-5. **Some mathematical functions missing**
-   - sqrt(), rand(), pow()
-   - Minimal TCK impact
-
 ---
 
 ## How to Use This Matrix

{graphforge-0.3.4 → graphforge-0.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphforge"
-version = "0.3.4"
+version = "0.3.6"
 description = "Composable graph tooling for analysis, construction, and refinement"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -270,4 +270,5 @@ dev = [
     "bandit[toml]>=1.7.0",
     "pre-commit>=3.6.0",
     "types-defusedxml>=0.7.0.20250822",
+    "interrogate>=1.7.0",
 ]