graphforge 0.3.7__tar.gz → 0.3.9__tar.gz

{graphforge-0.3.7 → graphforge-0.3.9}/.github/workflows/changelog-check.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
     types: [opened, synchronize, reopened, labeled, unlabeled]
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   check-changelog:
     name: Verify CHANGELOG Updated

{graphforge-0.3.7 → graphforge-0.3.9}/.github/workflows/docs.yml

@@ -36,7 +36,7 @@ jobs:
           fetch-depth: 0  # Fetch all history for git info
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -52,7 +52,7 @@ jobs:
 
       - name: Upload Pages artifact
         if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site/
 
@@ -69,4 +69,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{graphforge-0.3.7 → graphforge-0.3.9}/.github/workflows/publish.yaml

@@ -11,6 +11,6 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.1.0
       - run: uv build
       - run: uv publish

graphforge-0.3.9/.github/workflows/test.yml

@@ -0,0 +1,427 @@
+name: Test Suite
+
+on:
+  push:
+    branches: ["main", "develop"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download SNAP ego-facebook dataset
+        run: |
+          mkdir -p ~/.graphforge/datasets
+          curl -L -o ~/.graphforge/datasets/snap-ego-facebook.txt.gz https://snap.stanford.edu/data/facebook_combined.txt.gz
+        shell: bash
+
+      - name: Run unit tests
+        run: uv run pytest tests/unit -n auto --junitxml=test-results-unit.xml
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration -n auto -m "not snap" --junitxml=test-results-integration.xml
+
+      - name: Upload test results to Codecov
+        uses: codecov/codecov-action@v6
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: test-results-unit.xml,test-results-integration.xml
+          flags: ${{ matrix.os }}-py${{ matrix.python-version }}
+          report_type: test_results
+          fail_ci_if_error: false
+
+  lint:
+    name: Lint and Format Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Lint code
+        run: uv run ruff check .
+
+  type-check:
+    name: Type Checking (mypy)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run mypy type checker
+        run: uv run mypy src/graphforge --strict-optional --show-error-codes
+
+  security:
+    name: Security Scanning
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run bandit security scanner
+        run: uv run bandit -c pyproject.toml -r src/
+
+  tck-regression:
+    name: TCK Shard ${{ matrix.group }}/4
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        group: [1, 2, 3, 4]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Restore test durations cache
+        uses: actions/cache/restore@v5
+        with:
+          path: .test_durations
+          key: tck-durations-${{ github.ref }}
+          restore-keys: tck-durations-
+
+      - name: Run TCK shard ${{ matrix.group }}/4
+        id: tck_tests
+        continue-on-error: true
+        run: |
+          uv run pytest tests/tck/ -n auto \
+            --splits 4 --group ${{ matrix.group }} \
+            --splitting-algorithm duration_based_chunks \
+            --store-durations --durations-path=.test_durations_${{ matrix.group }} \
+            --junitxml=test-results-tck-${{ matrix.group }}.xml
+
+      - name: Upload shard results artifact
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: tck-shard-${{ matrix.group }}
+          path: |
+            test-results-tck-${{ matrix.group }}.xml
+            .test_durations_${{ matrix.group }}
+
+  tck-report:
+    name: TCK OpenCypher Compliance
+    runs-on: ubuntu-latest
+    needs: tck-regression
+    if: always()
+    permissions:
+      contents: read
+      actions: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download all shard results
+        uses: actions/download-artifact@v8
+        with:
+          pattern: tck-shard-*
+          run-id: ${{ github.run_id }}
+          merge-multiple: true
+          path: tck-results/
+
+      - name: Merge JUnit XML results
+        run: |
+          uv run python3 -c "
+          import glob, sys
+          from xml.etree import ElementTree as ET
+
+          files = sorted(glob.glob('tck-results/test-results-tck-*.xml'))
+          if not files:
+              print('No shard result files found')
+              sys.exit(1)
+
+          root = ET.parse(files[0]).getroot()
+          suite = root if root.tag == 'testsuite' else root.find('testsuite')
+
+          for f in files[1:]:
+              tree = ET.parse(f).getroot()
+              src = tree if tree.tag == 'testsuite' else tree.find('testsuite')
+              for tc in src.findall('testcase'):
+                  suite.append(tc)
+
+          tests = len(suite.findall('testcase'))
+          failures = len(suite.findall('.//failure'))
+          errors = len(suite.findall('.//error'))
+          suite.set('tests', str(tests))
+          suite.set('failures', str(failures))
+          suite.set('errors', str(errors))
+
+          ET.ElementTree(root).write('test-results-tck.xml', xml_declaration=True, encoding='utf-8')
+          print(f'Merged {len(files)} shards: {tests} tests, {failures} failures')
+          "
+
+      - name: Merge test durations for future balancing
+        run: |
+          uv run python3 -c "
+          import glob, json
+          files = glob.glob('tck-results/.test_durations_*')
+          merged = {}
+          for f in files:
+              with open(f) as fh:
+                  merged.update(json.load(fh))
+          with open('.test_durations', 'w') as fh:
+              json.dump(merged, fh)
+          print(f'Merged durations for {len(merged)} tests from {len(files)} shards')
+          " || echo "No duration files found, skipping merge"
+
+      - name: Save test durations cache
+        uses: actions/cache/save@v5
+        if: always()
+        with:
+          path: .test_durations
+          key: tck-durations-${{ github.ref }}-${{ github.run_id }}
+
+      - name: Report TCK compliance metrics
+        if: always()
+        run: uv run python3 scripts/tck_metrics.py test-results-tck.xml
+
+      - name: Report TCK performance metrics
+        if: always()
+        run: uv run python3 scripts/tck_perf_report.py test-results-tck.xml --threshold 5
+
+      - name: Upload TCK results to Codecov
+        uses: codecov/codecov-action@v6
+        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 merged TCK results artifact
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: tck-test-results
+          path: test-results-tck.xml
+
+  coverage-shard:
+    name: Coverage Shard ${{ matrix.group }}/4
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        group: [1, 2, 3, 4]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download SNAP ego-facebook dataset
+        run: |
+          mkdir -p ~/.graphforge/datasets
+          curl -L -o ~/.graphforge/datasets/snap-ego-facebook.txt.gz https://snap.stanford.edu/data/facebook_combined.txt.gz
+        shell: bash
+
+      - name: Run tests with coverage (shard ${{ matrix.group }}/4)
+        run: |
+          uv run pytest tests/unit tests/integration \
+            --splits 4 --group ${{ matrix.group }} \
+            --splitting-algorithm duration_based_chunks \
+            -n auto \
+            -m "not snap" \
+            --cov=src --cov-branch \
+            --cov-report=xml:coverage-${{ matrix.group }}.xml \
+            --junitxml=test-results-cov-${{ matrix.group }}.xml
+
+      - name: Upload coverage shard artifact
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: coverage-shard-${{ matrix.group }}
+          path: |
+            coverage-${{ matrix.group }}.xml
+            test-results-cov-${{ matrix.group }}.xml
+
+  coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    needs: coverage-shard
+    if: always()
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download all coverage shards
+        uses: actions/download-artifact@v8
+        with:
+          pattern: coverage-shard-*
+          run-id: ${{ github.run_id }}
+          merge-multiple: true
+          path: cov-results/
+
+      - name: Merge coverage reports
+        run: |
+          uv run python3 -c "
+          import glob, sys
+          from xml.etree import ElementTree as ET
+
+          files = sorted(glob.glob('cov-results/coverage-*.xml'))
+          if not files:
+              print('No coverage files found')
+              sys.exit(1)
+
+          base = ET.parse(files[0])
+          base_root = base.getroot()
+          base_packages = base_root.find('packages')
+
+          for f in files[1:]:
+              tree = ET.parse(f).getroot()
+              for pkg in tree.findall('.//package'):
+                  base_packages.append(pkg)
+
+          base.write('coverage.xml', xml_declaration=True, encoding='utf-8')
+          print(f'Merged {len(files)} coverage shards')
+          "
+
+      - name: Check coverage threshold
+        run: |
+          uv run python3 -c "
+          import xml.etree.ElementTree as ET, sys
+          tree = ET.parse('coverage.xml')
+          line_rate = float(tree.getroot().get('line-rate', 0))
+          pct = round(line_rate * 100, 1)
+          print(f'Coverage: {pct}%')
+          if pct < 85:
+              print(f'Coverage {pct}% is below 85% threshold')
+              sys.exit(1)
+          print('Coverage meets 85% threshold')
+          " || echo "Coverage check failed - see above for details"
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v6
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: full-coverage
+          name: codecov-full
+          fail_ci_if_error: false
+
+      - name: Upload test results to Codecov
+        uses: codecov/codecov-action@v6
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: cov-results/test-results-cov-*.xml
+          flags: full-suite
+          report_type: test_results
+          fail_ci_if_error: false
+
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report
+          path: coverage.xml

{graphforge-0.3.7 → graphforge-0.3.9}/.gitignore

@@ -176,3 +176,6 @@ tmp/
 # MkDocs build output
 site/
 tck_*.txt
+
+# Perf baseline results (machine-specific, generated by make test-perf)
+benchmarks/real_dataset_baseline_v*.json

{graphforge-0.3.7 → graphforge-0.3.9}/CHANGELOG.md

@@ -5,6 +5,77 @@ 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).
 
+## [Unreleased]
+
+## [0.3.9] - 2026-05-04
+
+### Added
+- **LALR(1) parser migration** (#365, #430) — grammar refactored to LALR(1); linear-time parsing replaces Earley; unknown function names now detected at parse time; 586 new parser tests; OOM-safe local coverage via sharded `make coverage`
+- **Property equality index for O(1) node lookup** (#390, #427) — in-memory `_prop_index` (prop → value → {node\_id}) on `Graph`; `get_nodes_by_property` and `get_nodes_by_label_and_property` methods; executor `_extract_equality_hints` replaces full scan with index lookup when a `ScanNodes` is followed by a simple equality `Filter`; index maintained on `SET`/`REMOVE`/`DELETE`
+- **Bulk ingestion API** (#389, #444) — `create_node_bulk`, `create_relationship_bulk` (skip per-call Pydantic validation); `bulk_ingest()` context manager defers statistics rebuilds until exit via `_flush_deferred_stats()`; CSV loader uses bulk path; significant throughput improvement for dataset loading
+- **Real-dataset QA and performance profiling suite** (#417, #419) — 5-tier perf suite (karate 34n, ego-facebook 4k, amazon 334k, livejournal 4M, orkut 117M edges); `scripts/perf_report.py` renders baseline/delta Markdown tables; `make test-perf`, `make test-perf-xs`, `make test-perf-large`, `make test-perf-slow` targets; L/XL tier benchmarks added; `perf_slow` marker applied consistently (#440, #441)
+- **`elementId()` scalar function** (#211, #447) — GQL-spec `elementId(node|rel)` returns the element id as `CypherString`; `id()` continues to return `CypherInt`; NULL-safe; arity-checked
+- **Scale limits documentation** — `docs/reference/scale-limits.md` explains LIMIT-respecting (~20M edges) vs full-scan (~1M edges) performance ceilings; README graph-size claim updated to reflect edge-count as binding constraint (#443)
+- **`make pre-push-fast`** (#429, #437) — fast-fail pre-push shortcut (format, lint, type, security, docstrings; no coverage); inline coverage thresholds (85% total, 90% patch)
+
+### Fixed
+- **Fixed-length hop ignores rel predicate** (#431, #439) — fixed-length traversal now evaluates `rel_pattern.predicate` inline; parser predicate whitelist replaced with open accept
+- **var-length relationship predicates** (#381, #425) — `_var_length_reachable` now evaluates inline relationship predicates (e.g. `[*1..3 {weight: 1}]`) at each hop instead of ignoring them
+- **Cross-hop edge uniqueness in multi-segment patterns** (#382, #425) — `initial_used_edge_ids` seeds the visited-edge set from prior hops, preventing the same edge being traversed twice across pattern segments
+- **SQLite delete persistence** (#409, #421) — deleted nodes and edges now removed from SQLite backend; previously they resurrected on reload
+- **SQLite bulk I/O** (#392, #421) — `save_nodes_bulk` / `save_edges_bulk` use `executemany`; `_save_graph_to_backend` wrapped in rollback; resolves >20s hang on M-tier reload
+- **`sys.setrecursionlimit` thread safety** (#433, #445) — limit set once in `CypherParser.__init__` instead of per-request get/set/restore, eliminating races in concurrent parser use
+- **Transaction rollback restores ID counters** (#412) — `rollback()` restores `_next_node_id` and `_next_edge_id`, preventing ID gaps after aborted transactions
+- **Closed-instance guard** (#411) — `execute()` and mutation methods raise `RuntimeError` after `close()`
+- **`DatasetInfo` rejects `ftp://` URLs** (#414)
+- **TCK metrics CI gate** (#410) — `tck_metrics.py` exits non-zero on TCK failures
+
+### Performance
+- **UNWIND + WITH LIMIT short-circuit** (#393, #443) — `_pipeline_limit` reverse-scan treats pass-through `With(limit_count=N, no sort, no filter)` as transparent; `_execute_unwind` respects `row_limit` and exits early; `UNWIND range(1M, 2M) AS i WITH i LIMIT 3000 RETURN sum(i)` drops from ~4.5s to <10ms
+- **LIMIT short-circuit for scan and expand operators** (#422, #423) — `_pipeline_limit` look-ahead stops scan/expand at row budget; write operators and Filter block short-circuit to preserve correctness
+- **SQLite PRAGMA tuning** (#392, #446) — `synchronous=NORMAL` (eliminates `fdatasync` per commit), 64 MB page cache (`cache_size=-65536`), `temp_store=MEMORY`; safe with WAL mode for analytical workloads
+- **Lazy statistics timestamp** — `_stats_last_updated` stamped at read time in `get_statistics()` rather than on every add; `_defer_stats` flag eliminates per-edge stat overhead during bulk ingest
+
+### CI / Tooling
+- **Test suite zero-base renovation** (#428, #438) — fixture strategy audit, duplication removal, marker consistency, parametrization improvements across unit and integration suites
+- **GHA actions updated** — `actions/upload-artifact` v7, `actions/download-artifact` v8, `codecov/codecov-action` v6, `actions/upload-pages-artifact` v5, `astral-sh/setup-uv` v8.1.0
+
+## [0.3.8] - 2026-05-02
+
+### Fixed - TCK Feature Completeness (3885/3885 passing)
+- **Nanosecond precision in temporal types** — `CypherDateTime` and `CypherTime` now store a `_ns_residue` (0–999) for sub-microsecond precision; `_components` tuple extended to 8 elements with nanoseconds; construction, accessors, arithmetic, comparison, and serialization all updated (#224)
+- **Statement clock caching** — `now()`, `datetime()`, `date()`, `time()` (without arguments) now return consistent values within a single query by caching the start time via `time.time_ns()` (#224)
+- **Extreme year support** — dates/datetimes outside Python's 1–9999 range now handled via `_WideDate` / `_WideDateTime` classes; durations too large for `timedelta` use `_BigDuration`; Julian Day Number arithmetic for cross-extreme-year duration computation (#224)
+- **IANA timezone name preservation** — `CypherDateTime` stores the IANA zone name (e.g. `Europe/Stockholm`) separately; `.timezone` accessor returns the zone name rather than the numeric offset; `utcoffset()` now receives a concrete datetime for DST-aware lookup (#224)
+- **Aggregate detection in QuantifierExpression** — `ALL(ok IN collect(...) WHERE ok)` patterns now correctly detected as aggregate-containing; planner emits `Aggregate` instead of `Project` (#224)
+- **OPTIONAL MATCH multi-WHERE placement** — multiple `WHERE` clauses no longer overwrite each other; multi-hop OPTIONAL MATCH WHERE is emitted after all hops so all variables are bound (#224)
+- **`coalesce()` type inference** — return type is inferred from argument types so `MATCH (x)` after `WITH coalesce(a, b) AS x` accepts node-typed variables (#224)
+- **Non-deterministic aggregate arguments** — `count(rand())` and similar expressions now raise `AmbiguousAggregationExpression` per the openCypher spec (#224)
+- **Temporal accessor for extreme-year datetimes** — `year`, `month`, `day`, `hour`, `minute`, `second` accessors work on `_WideDateTime`-backed `CypherDateTime` values (#224)
+- **All 23 xfail markers removed** — previously marked as expected failures; all were fixable (#224)
+
+### Added
+- **75-test unit coverage for extreme temporal classes** — `tests/unit/types/test_extreme_temporal_values.py` covers `_WideDate`, `_WideDateTime`, `_BigDuration`, extreme-year construction/accessors, IANA timezone preservation, and large duration handling
+
+### Fixed
+- **WITH clause WHERE filtering and variable scoping** (#362) — `WITH n WHERE n.age > 30` now correctly filters post-projection; chained WITH propagates bindings properly
+- **Triadic OPTIONAL MATCH semantics** (#302 partial) — `OPTIONAL MATCH (a)-[r]->(b)` with pre-bound `b` now correctly filters to only edges reaching that specific destination (LEFT JOIN semantics)
+- **Relationship type disjunction without colon prefix** (#363) — `[:KNOWS|FOLLOWS]` (pipe without colon on subsequent types) now parses correctly
+- **Multi-CREATE variable scoping** (#364 partial) — variables created in one CREATE clause are now visible in subsequent CREATE clauses within the same query
+
+### Performance
+- **O(n²) → O(1) graph statistics updates** (#366) — `_update_statistics_after_add_edge` no longer scans all edges on every insert; replaced with incremental `_unique_sources_by_type` tracking. Eliminated 2,000+ Pydantic `model_copy()` calls per 1,000-node graph by switching to mutable counters with lazy `GraphStatistics` construction
+- **Parser fast path for long CREATE sequences** (#366) — queries with many consecutive CREATE clauses (e.g. the TCK movie graph with 971 CREATEs) are pre-split into batches of 5 before Earley parsing, reducing wall-clock time from 27 minutes to ~26 seconds. See docs/development/parser-performance-analysis.md for full analysis and the LALR(1) migration plan (issue #365)
+
+### CI
+- **TCK sharding across 4 parallel runners** — TCK tests now split using `pytest-split` with duration-based balancing (~4x faster CI)
+- **Coverage sharding** — coverage collection also split across 4 shards and merged in report job
+- **Python 3.14 experimental matrix** — added as non-blocking `continue-on-error` entries
+- **TCK performance reporting** — new `scripts/tck_perf_report.py` runs after each TCK run, reporting tests over 5s and tracking use-case tests (movie graph, school graph) for performance regression detection
+
+### TCK Coverage
+- **3,885 / 3,885 passing (100%)** — first release with zero TCK failures and zero expected failures
+
 ## [0.3.7] - 2026-04-07
 
 ### Added - Functions
@@ -38,7 +109,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Temporal select-into constructors** (#334) — cross-type temporal projection (`date({date: other})`, `localdatetime({datetime: dt})`, etc.) with component overrides; null propagation, hour-overflow normalization, and timezone conversion all correct
 
 ### TCK Coverage
-- **~2,894 passing** (up from ~2,507 at v0.3.6) — +387 net new passing scenarios
+- **3,235 / 3,885 passing (83.3%)** (up from ~2,507 at v0.3.6) — +728 net new passing scenarios
 - Theme: ORDER BY correctness, aggregation, operator precedence, graph semantics, temporal completeness
 
 ## [0.3.6] - 2026-02-28

{graphforge-0.3.7 → graphforge-0.3.9}/CLAUDE.md

@@ -51,6 +51,16 @@ make pre-push
 
 Runs: format-check, lint, type-check, coverage (85% total, 90% patch).
 
+**Before running tests locally during planning:** If the branch has no committed changes yet (i.e., you're still in the planning phase), check the last CI run instead of running the full test suite locally. This avoids OOM errors from running all tests unnecessarily.
+
+```bash
+# Check last CI run status and test results
+gh run list --branch main --limit 5
+gh run view <run-id> --log-failed   # see only failed tests
+```
+
+Only run tests locally once you have actual code changes to validate.
+
 ### 5. Commit with Issue Number
 
 ```bash
@@ -77,16 +87,21 @@ GitHub automatically closes the issue when PR merges.
 ## Development Commands
 
 ```bash
-make pre-push          # Run all checks (mirrors CI)
+make pre-push          # Run all checks (mirrors CI): format, lint, type, security, docstrings, coverage + thresholds
+make pre-push-fast     # Fast checks only (no coverage, ~30s): format, lint, type, security, docstrings
 make test              # All tests
 make test-unit         # Unit tests only
 make test-integration  # Integration tests only
-make coverage          # Run with coverage
+make coverage          # Run with coverage + validate thresholds (sharded, includes 85%/90% checks)
+make coverage-quick    # Coverage on unit tests only (fast feedback during development)
 make coverage-report   # View HTML coverage report
 make coverage-diff     # Coverage for changed files only
 
 # Run tests in parallel (4x faster for TCK)
 pytest tests/ -n auto
+
+# Override worker count (default 4, lower to reduce memory)
+PYTEST_WORKERS=2 make test
 ```
 
 **Coverage Requirements:**
@@ -94,6 +109,8 @@ pytest tests/ -n auto
 - Patch: 90% minimum for changed files
 - Best practice: Aim for 100% on new code
 
+**When to use `pre-push-fast`:** iterating on non-test changes (refactors, docs, config). Always run the full `pre-push` before opening a PR.
+
 ## Architecture: 4-Layer System
 
 ```