peql 0.3.0__tar.gz

peql-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  build-and-test:
+    name: build · fmt · clippy · test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust (stable)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: rustfmt
+        run: cargo fmt --all --check
+
+      - name: clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: test
+        run: cargo test
+
+      - name: build (release)
+        run: cargo build --release
+
+      # The platform adapter (T03 signed-bundle source) is feature-gated.
+      - name: clippy (platform)
+        run: cargo clippy --all-targets --features platform -- -D warnings
+
+      - name: test (platform)
+        run: cargo test --features platform
+
+      # Sanity-check that the examples actually run with no external services.
+      - name: run examples
+        run: |
+          for ex in plain_sql column_masking row_filter dp_noise contract_query graph_query; do
+            echo "::group::cargo run --example $ex"
+            cargo run --example "$ex"
+            echo "::endgroup::"
+          done
+          echo "::group::cargo run --example platform_bundle --features platform"
+          cargo run --example platform_bundle --features platform
+          echo "::endgroup::"

peql-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "pages-${{ github.event_name == 'pull_request' && github.ref || 'deploy' }}"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install documentation dependencies
+        run: python -m pip install -r docs/requirements.txt
+      - name: Build site
+        run: sphinx-build -W --keep-going -b html docs docs/_build/html
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - id: deployment
+        uses: actions/deploy-pages@v4

peql-0.3.0/.github/workflows/python-wheels.yml

@@ -0,0 +1,79 @@
+name: python-wheels
+
+# Build and publish pip-installable wheels. Release tags publish through PyPI
+# Trusted Publishing; manual runs build and test artifacts only.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: bindings/python
+
+jobs:
+  wheels:
+    name: wheels (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheels (abi3 — one wheel per platform covers Python ≥ 3.9)
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: bindings/python
+          command: build
+          args: --release --out dist
+          manylinux: auto
+
+      - name: Smoke-test the wheel
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip pyarrow pytest
+          python -m pip install --no-index --find-links dist peql
+          python -m pytest -q
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: bindings/python/dist/*.whl
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          working-directory: bindings/python
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: bindings/python/dist/*.tar.gz
+
+  publish:
+    name: publish to PyPI
+    needs: [wheels, sdist]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/peql
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish tested distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

peql-0.3.0/.gitignore

@@ -0,0 +1,24 @@
+# Rust build artifacts
+/target
+**/target
+**/*.rs.bk
+
+# Python / maturin
+.venv*/
+**/__pycache__/
+*.so
+*.pyd
+bindings/python/dist/
+*.egg-info/
+.pytest_cache/
+
+# Backtrace / debug
+*.pdb
+
+# macOS
+.DS_Store
+
+# Editor / IDE
+/.idea
+/.vscode
+*.swp

peql-0.3.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is loosely
+based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.3.0] — graph queries, peQL naming, and documentation
+
+This release follows `0.2.0`. The premature `v2.0.0` tag is withdrawn; the
+graph work below is included in `0.3.0` instead. The Rust crate and Python
+package are now named `peql`. The high-level Rust query type is `Engine`;
+`K04DEngine` remains available as a separate lower-level Rust API. The
+documentation is rebuilt with Sphinx and organized into learning, how-to,
+reference, explanation, and contribution paths.
+
+peQL traverses compiled business-process graphs in plain SQL, governed by
+the same contract policy as tables.
+
+- **Seven SQL table functions**: `graph_node`, `graph_neighbors`, `graph_edges`,
+  `graph_subtree`, `graph_path`, `graph_reachable`, and the relational
+  `graph_nodes` — each returns an ordinary table that composes with joins,
+  CTEs and aggregation. Positional arguments; results disclose
+  `snapshot_version` and (where capped) `truncated`.
+- **Governed traversal**: a policy-filtered node is a **wall** — absent from
+  every result *and* non-traversable (no path routes through it; nothing
+  reachable only via it is reachable) — closing the topology-leak class. A
+  graph-only `edge_filter` hides relationships between visible nodes. Column
+  masks run through the real masking operators, byte-identical to tables.
+  Deny and unknown-graph are byte-identical (no existence oracle); unknown
+  nodes return near-miss suggestions.
+- **Snapshot bundles** (G01 format): loaded from `nodes/edges/edges_rev.parquet`
+  + `manifest.json` with mandatory sha256 + `bundle_format` verification and
+  structural invariant checks; traversal runs on the precompiled CSR offset
+  columns — no query-time index build. Per-engine cache keyed by
+  (snapshot, policy fingerprint): bundles load once; different policies never
+  share a governed structure. v1 envelope ≤50k nodes / 200k edges, enforced.
+- **Contract format**: graph datasets bind via `binding.graph_snapshot`;
+  policy via `masks`, `node_filter` (row_filter alias over node columns) and
+  `edge_filter`. `ResolvedPolicy` gains `graph_edge_filter`.
+- **Python parity**: the same graph SQL works through the wheel unchanged;
+  list columns (`data_refs` …) round-trip to pyarrow.
+- Verified end-to-end against the real compiled `zijani-operations` bundle
+  (271 nodes / 562 edges): examples/graph_query.rs + 10 SQL E2E tests,
+  33 traversal-algorithm tests, and bundle loader tests.
+- Design + as-built spec: [`docs/GRAPH-QUERY.md`](docs/GRAPH-QUERY.md).
+
+## [0.2.0] — contract resolution spine + platform adapter
+
+Turned the engine from "mask a hand-fed batch" into "query a contract": you now
+name a contract-bound dataset in SQL and get governed rows.
+
+- **Contract resolution spine.** `SELECT … FROM "<dataset-uri>"` resolves the
+  governing contract for the caller and the physical data location, then applies
+  the contract's masking, row filtering and DP noise inside the query plan.
+  New modules: `policy` (`ResolvedPolicy` — the engine-agnostic enforcement
+  primitive), `contract_source` (`ContractSource` + `JsonContractSource`),
+  `binding` (`BindingResolver` + local Parquet loader), `contract_table_provider`
+  (`ContractTableProvider`), `catalog` (lazy DataFusion `SchemaProvider`/
+  `CatalogProvider`), and `engine` (`Engine`).
+- **Open-source path.** A simple JSON contract format + local Parquet — no
+  services, no `protoc`. See `docs/CONTRACT-FORMAT.md`.
+- **Platform adapter** (`--features platform`). `PlatformBundleSource` fetches a
+  Griot Cloud T03 signed bundle over HTTP, verifies its ECDSA-P256 signature
+  (canonical hashing mirrored from T03's `bundle-signer`), and maps it to the
+  same `ResolvedPolicy`. Exercised offline against the real committed bundle
+  fixture.
+- New examples: `contract_query` (standalone) and `platform_bundle` (platform).
+- Docs: `docs/USAGE.md`, `docs/CONTRACT-FORMAT.md`, `docs/ARCHITECTURE.md`.
+- The pre-existing enforcement operators are reused unchanged.
+
+## [0.1.0] — initial snapshot
+
+Initial standalone snapshot of the peQL query engine, **copied** out of the
+Griot Cloud platform monorepo.
+
+- **Source:** `griot-cloud` @ commit `5b999ed0010aeb86ae703076798f035b9c0c9121`
+  (path `zone-k/k04-workers/k04d-query-rs/`).
+- Trimmed the cloud-only deployment glue (HTTP service wrapper, GCS/pgvector/
+  Redis clients, container/build manifests) and the legacy gRPC server so the
+  crate builds and runs standalone with only Rust + cargo.
+- Pruned the now-unused dependencies; the default build needs no `protoc` and no
+  system libraries.
+- Kept the engine intact: the DataFusion optimizer rules and physical operators
+  (contract check, row filter, column masking, differential-privacy noise,
+  attestation), the sealed engine core, and the DDL guard.
+- Added four runnable examples (`plain_sql`, `column_masking`, `row_filter`,
+  `dp_noise`) that demonstrate governed output with zero external services.
+- `lance` columnar support retained as an optional feature (off by default;
+  requires `protoc`).
+
+The engine's behaviour is unchanged from the source commit; this release is a
+packaging + documentation pass, not a redesign.

peql-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to peQL
+
+Thanks for your interest. peQL is a standalone snapshot of the query engine
+from the Griot Cloud platform (see [Provenance](README.md#provenance)).
+
+## Development setup
+
+You only need a recent stable Rust toolchain (≥ 1.88). Everything else is
+vendored through cargo.
+
+```bash
+git clone <this-repo> peql && cd peql
+cargo build
+cargo test
+```
+
+## Before you open a PR
+
+Run the same gates CI runs (these must all pass):
+
+```bash
+cargo fmt --all --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+cargo build --release
+```
+
+- Keep the default feature set building **without `protoc`**. Anything that
+  needs `protoc` (e.g. the Lance columnar path) must stay behind the `lance`
+  feature.
+- Match the surrounding style: the engine source predates clippy's inline
+  format-args lint, which is allowed crate-wide — don't churn unrelated lines.
+- Add or update an example when you add user-visible behaviour, and make sure
+  `cargo run --example <name>` still works with no external services.
+
+## Scope
+
+This repo packages the engine for standalone use. Deeper changes that invert the
+engine's dependencies (so the upstream platform can consume this as a published
+library) are tracked separately and are out of scope here. Bug fixes,
+documentation, examples, and build/CI improvements are all welcome.
+
+## Reporting issues
+
+Please include the command you ran, the full output, your `rustc --version`, and
+your OS. For enforcement bugs (masking/row-filter/DP), a minimal reproduction
+that constructs the engine in memory (as the examples do) is ideal.