From c4c455835c0a303c34749a80183bcad85ff6ff25 Mon Sep 17 00:00:00 2001 From: Khemchand Joshi Date: Wed, 8 Jul 2026 18:29:21 +0530 Subject: [PATCH] =?UTF-8?q?chore(release):=200.6.4=20=E2=80=94=20read-only?= =?UTF-8?q?=20graph=20query=20(feat-015)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bump 0.6.3 -> 0.6.4 + uv lock; roll CHANGELOG [Unreleased] -> [0.6.4]; README Status -> 0.6.4; release notes docs/release/0.6.4.md + index. Mark feat-015 shipped (spec Status + TRACKER). 0.6.4 ships the read-only structural query surface (ckg query --graph / ckg_query): a validated Cypher-subset AST compiled to native Cypher (Kuzu, Neo4j) or interpreted over the GraphStore ABC (SurrealDB + any backend), identical rows across all three (conformance-proven), bounded and read-only. Plus a resolver fix so re-exported package base classes resolve (INHERITS/CALLS recall). Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 13 +++++ README.md | 7 ++- docs/features/TRACKER.md | 2 +- .../feat-015-read-only-graph-query.md | 2 +- docs/release/0.6.4.md | 53 +++++++++++++++++++ docs/release/README.md | 1 + pyproject.toml | 2 +- uv.lock | 2 +- 8 files changed, 76 insertions(+), 6 deletions(-) create mode 100644 docs/release/0.6.4.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ff23004..190cc21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ on a schema mismatch is **rebuild** (ADR-0006). ## [Unreleased] +## [0.6.4] — 2026-07-08 + ### Added - **feat-015 — read-only graph query surface (`ckg query --graph` / `ckg_query`).** @@ -33,6 +35,17 @@ on a schema mismatch is **rebuild** (ADR-0006). - New `query:` config block; guide 13. `NodeKind`/`EdgeKind` vocabulary unchanged. +### Fixed + +- **Resolver: re-exported package symbols now resolve as base classes.** A base + class imported via an absolute path and re-exported through a package + `__init__.py` (e.g. `class KuzuGraphStore(GraphStore)`, where `GraphStore` is + defined in `core.contracts` and re-exported by `core/__init__.py`) previously + produced no `INHERITS` edge. The resolver now computes a package re-export + namespace (fixpoint) and binds through it — improving `INHERITS` and `CALLS` + recall for every consumer (retrieval, impact, repo-map), not just the query + surface. + ## [0.6.3] — 2026-07-07 ### Added diff --git a/README.md b/README.md index 4383484..8813f34 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,11 @@ ckg serve-mcp --repo . # → 10 read-only tools for your agent across services** — `ckg services-map` / `ckg trace` draw the cross-service call graph (HTTP client → route, matched by path or OpenAPI contract). -**Status: 0.6.3 — org-scale, built in one command, wired in one, kept fresh -automatically.** 0.5 added central hosting, a federated multi-repo workspace, and +**Status: 0.6.4 — org-scale, built in one command, wired in one, kept fresh +automatically, and now queryable.** 0.6.4 adds a read-only **structural query** +surface (`ckg query --graph` / the `ckg_query` tool) — a guard-railed Cypher +subset for the exact questions no typed verb covers, identical across every +storage backend. 0.5 added central hosting, a federated multi-repo workspace, and cross-service tracing; 0.6 adds the **build side** — stand up a multi-repo CKG from one `workspace.yaml` + one config + `ckg build --workspace` (members local or by git URL), with fail-fast `ckg doctor` validation and config/CLI-controlled diff --git a/docs/features/TRACKER.md b/docs/features/TRACKER.md index 5a6e3e1..4114f7b 100644 --- a/docs/features/TRACKER.md +++ b/docs/features/TRACKER.md @@ -59,7 +59,7 @@ Legend: `proposed` → `accepted` → `in-progress` → `shipped` (also | [012](feat-012-llm-enrichment.md) | LLM enrichment (summaries, tags) | 3 diff | 0.4 | shipped (tags + summaries) | 006 | — | ✅ | | [013](feat-013-agent-auto-configuration.md) | Agent auto-configuration & frictionless first run | 4 adoption | 0.6.2 | **shipped (0.6.2)** | 008 | — | ✅ | | [014](feat-014-watch-and-ci-indexing.md) | Watch mode (local) + CI-triggered central indexing | 4 adoption | 0.6.3 | **shipped (0.6.3)** | 004 | — | ✅ | -| [015](feat-015-read-only-graph-query.md) | Read-only graph query (`ckg query --graph` / `ckg_query`) | 1 serve | 0.6.4 | **in-progress (chunk 1)** | 001,003,008 | — | ✅ | +| [015](feat-015-read-only-graph-query.md) | Read-only graph query (`ckg query --graph` / `ckg_query`) | 1 serve | 0.6.4 | **shipped (0.6.4)** | 001,003,008 | — | ✅ | --- diff --git a/docs/features/feat-015-read-only-graph-query.md b/docs/features/feat-015-read-only-graph-query.md index 8d67ee9..756cdff 100644 --- a/docs/features/feat-015-read-only-graph-query.md +++ b/docs/features/feat-015-read-only-graph-query.md @@ -6,7 +6,7 @@ |---|---| | **ID** | feat-015 | | **Title** | Read-only, guard-railed graph query surface (Cypher-subset) + `ckg_query` verb/tool | -| **Status** | in-progress | +| **Status** | shipped (0.6.4) | | **Target version** | 0.6.4 | | **Layer** | 1 serve (retrieval & serving) — escape-hatch complement to the typed verbs | | **Area** | `store` (query AST, validator, per-backend compilers, execution) · `serve` (`ckg_query` tool) · CLI | diff --git a/docs/release/0.6.4.md b/docs/release/0.6.4.md new file mode 100644 index 0000000..051d7d0 --- /dev/null +++ b/docs/release/0.6.4.md @@ -0,0 +1,53 @@ +# agentforge-graph 0.6.4 — ask the graph anything structural + +**Theme: query.** The CKG already answered questions through fixed, typed verbs +(`ckg search`, `ckg impact`, `ckg routes`, …) — each great for the question it +was built for, but a **closed set**. 0.6.4 adds the escape hatch: a read-only, +guard-railed **structural query** surface so any exact question over the graph is +answerable directly, without us shipping a new verb. + +## Highlights + +### `ckg query --graph` / `ckg_query` — a read-only Cypher subset (feat-015) + +```bash +# "classes tagged Repository with no inbound CALLS", "interfaces implemented by many classes", … +ckg query --graph 'MATCH (c:Class)-[:IMPLEMENTS]->(i:Interface) + RETURN i.name, count(c) AS impls ORDER BY impls DESC' + +ckg query --graph 'MATCH (f:Function) WHERE NOT (f)<-[:CALLS]-() RETURN f.name, f.path' +ckg query --graph '' --format json # {columns, rows, truncated, stopped_reason} +ckg query --schema # the queryable vocabulary +``` + +- **The escape hatch, not a replacement.** For semantic "find code about X" use + `ckg_search`; for "who calls this" use `ckg_impact`. `ckg_query` is for *precise + structural* questions with exact predicates — `MATCH` patterns (directions, + bounded var-length `[:CALLS*1..3]`), `WHERE` (comparisons, `AND/OR/NOT`, `IN`, + `STARTS/ENDS WITH`, `CONTAINS`, pattern existence), `RETURN` with + `count/min/max/avg/collect`, `ORDER BY`/`SKIP`/`LIMIT`. +- **Safe by construction.** Caller text is never executed. It is parsed into a + validated AST (the single trust boundary), then **compiled** to native Cypher + (Kuzu, Neo4j) or **interpreted** over the storage API (SurrealDB, and any + backend without a query language). Writes/DDL, procedure calls, unbounded paths, + and un-joined Cartesian products are rejected with a clear reason — never a + stack trace. +- **Identical on every backend.** A shared conformance suite proves Kuzu, Neo4j, + and SurrealDB return the same rows for the same query. +- **Bounded, no silent caps.** `query.max_rows` / `timeout_ms` / `max_expansions` + are enforced on every backend and reported via `truncated` + `stopped_reason`, + so a partial answer is never mistaken for a complete one. +- **For agents too.** A capability-gated `ckg_query` MCP tool (present only when + the backend is query-capable and `query.allow_in_mcp` is on) with the usual + staleness envelope; `ckg status` reports the query-language version. + +See the new guide: **[Ad-hoc structural queries](../guides/13-graph-query.md)**. + +## Fixed + +- **Re-exported base classes now resolve.** A base class imported via an absolute + path and re-exported through a package `__init__.py` (e.g. + `class KuzuGraphStore(GraphStore)`) previously produced no `INHERITS` edge. The + resolver now binds through a package re-export namespace — improving `INHERITS` + and `CALLS` recall for **every** consumer (retrieval, impact, repo-map), not + just the query surface. diff --git a/docs/release/README.md b/docs/release/README.md index 943dbc5..ce8ee75 100644 --- a/docs/release/README.md +++ b/docs/release/README.md @@ -8,5 +8,6 @@ narrative. | Version | Notes | Theme | |---|---|---| +| [0.6.4](0.6.4.md) | `ckg query --graph` / `ckg_query` — read-only structural query | query | | [0.6.3](0.6.3.md) | `ckg watch` + `ckg ci init` — keep the graph fresh | freshness / ops | | [0.6.2](0.6.2.md) | `ckg setup` — agent auto-configuration | adoption | diff --git a/pyproject.toml b/pyproject.toml index 0ba3740..e59b262 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,7 +2,7 @@ # scaffold default. Managed-file upgrades will treat this as forked. [project] name = "agentforge-graph" -version = "0.6.3" +version = "0.6.4" description = "Code Knowledge Graph (CKG) engine + agent toolset, built on AgentForge." readme = "README.md" license = "Apache-2.0" diff --git a/uv.lock b/uv.lock index e01d1ae..5fa5583 100644 --- a/uv.lock +++ b/uv.lock @@ -40,7 +40,7 @@ wheels = [ [[package]] name = "agentforge-graph" -version = "0.6.3" +version = "0.6.4" source = { editable = "." } dependencies = [ { name = "agentforge-anthropic", extra = ["anthropic"] },