Add architecture skill for the index query engine#5467
Merged
Conversation
Distills the query engine's design into .claude/skills/index-query-engine/ SKILL.md — the two-pass compilation pipeline, the Postgres/SQLite dual-adapter constraints, table-valued fan-out semantics, filter polarity, synthetic search-doc keys, and the parity contract with instance-filter-matcher.ts — and points to it from a comment on IndexQueryEngine. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds contributor-facing documentation for the IndexQueryEngine architecture by introducing a new Claude skill document and linking to it from the engine source, with no runtime behavior changes.
Changes:
- Added an inline comment in
IndexQueryEnginepointing readers to centralized architectural guidance before making semantic changes. - Added a new skill document describing the index query engine’s two-pass compilation pipeline, adapter parity constraints, and client-side matcher contract.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| packages/runtime-common/index-query-engine.ts | Adds a pointer comment directing future edits to the new architecture doc. |
| .claude/skills/index-query-engine/SKILL.md | New architecture skill documenting invariants/constraints of the index query engine. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Expands the skill with a dedicated section on plural-path compilation: the shared fullkey dialect between sqlite json_tree and the custom pg jsonb_tree, a worked example of the anchor predicate, the alias-collapse rule that binds the value test and its anchor to one tree row, its composition consequences, and the container-row anchoring used for null checks. Also prefixes module paths with packages/ so file references are navigable from the repo root. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
burieberry
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a Claude skill documenting the architecture of the index query engine, and a comment on
IndexQueryEnginepointing readers to it. No behavior changes — one code comment plus a new markdown file.Why
index-query-engine.tscompilesQueryfilter trees into SQL that must run identically on Postgres and SQLite, and most of its design constraints are invisible at any single call site: the two-pass (async definition-driven, then mechanical) compilation, why plural fields route throughjson_tree()with a fullkey-confinement predicate, which differences belong in-band vs in the SQLiteadjustSQLtext rewrites, the existential semantics of table-valued fan-out underGROUP BY(including howtypesconditions compose — and don't), filter polarity, synthetic search-doc keys, and the parity contract with the client-sideinstance-filter-matcher.ts.The skill (
.claude/skills/index-query-engine/SKILL.md) captures those invariants in one place so changes to the engine — new filter operators, new synthetic keys, changes to path compilation — are made with the whole contract in view.🤖 Generated with Claude Code