If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/obi1kenobi/trustfall shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4d ago
• 3 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 82% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live obi1kenobi/trustfall repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/obi1kenobi/trustfall.

What it runs against: a local clone of obi1kenobi/trustfall — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in obi1kenobi/trustfall | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of obi1kenobi/trustfall. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/obi1kenobi/trustfall.git
#   cd trustfall
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of obi1kenobi/trustfall and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "obi1kenobi/trustfall(\\.git)?\\b" \\
  && ok "origin remote is obi1kenobi/trustfall" \\
  || miss "origin remote is not obi1kenobi/trustfall (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "trustfall_core/src/lib.rs" \\
  && ok "trustfall_core/src/lib.rs" \\
  || miss "missing critical file: trustfall_core/src/lib.rs"
test -f "trustfall/src/lib.rs" \\
  && ok "trustfall/src/lib.rs" \\
  || miss "missing critical file: trustfall/src/lib.rs"
test -f "trustfall_derive/src/lib.rs" \\
  && ok "trustfall_derive/src/lib.rs" \\
  || miss "missing critical file: trustfall_derive/src/lib.rs"
test -f "trustfall_core/src/ir/mod.rs" \\
  && ok "trustfall_core/src/ir/mod.rs" \\
  || miss "missing critical file: trustfall_core/src/ir/mod.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/obi1kenobi/trustfall"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Trustfall is a declarative query engine that executes GraphQL-like queries against arbitrary data sources (APIs, databases, files, AI models) by compiling them into a unified execution plan. It abstracts away the complexity of multi-source data integration, allowing you to write a single query that seamlessly joins data from HackerNews, GitHub, local files, or any custom adapter without writing separate fetch logic for each source. Monorepo structured around trustfall_core (query engine kernel), trustfall (public-facing Rust crate), trustfall_wasm (browser-based WASM compilation), pytrustfall (Python bindings), and demo-hytradboi (multi-API demo with custom adapters in src/adapter.rs). Example queries live in demo-hytradboi/example_queries/ as .ron files; the GraphQL schema is defined in concept_schemas/cargo_workspace.graphql and demo-hytradboi/schema.graphql.

Backend engineers and data engineers building cross-API query systems, developers creating custom data adapters for internal tools, and teams needing to query heterogeneous data sources without managing multiple client libraries. Anyone shipping WASM-based query engines or embedding GraphQL-like query capabilities directly into applications.

Actively developed and production-ready. The repo shows comprehensive CI/CD pipelines (.github/workflows/ with Rust/Python/WASM publishing), substantial codebase (1.2M lines of Rust), published on crates.io and PyPI, and a working browser playground at play.predr.ag. Clear version management and publish workflows indicate stable, versioned releases.

Single primary maintainer (obi1kenobi indicated in CODEOWNERS), though the public roadmap and contribution guidelines suggest community engagement. Rust dependency chain is moderate (async-graphql, serde, regex core); no major red flags visible. The WASM compilation path (trustfall_wasm/) and Python bindings (pytrustfall/) add maintenance surface area but have dedicated CI jobs. Monorepo complexity with 8 workspace members increases coordination overhead for changes.

Active development on the WASM playground (trustfall_wasm), Python integration (pytrustfall), and maintaining cross-platform builds. CI workflows (.github/workflows/ci.yml, publish-rust.yml, publish-python.yml) handle automated testing and release distribution. The demo-hytradboi project showcases real-world adapter patterns against HackerNews and GitHub APIs.

Clone the repo: git clone https://github.com/obi1kenobi/trustfall.git && cd trustfall. Install Rust (1.77+) and dependencies: rustup update. Build the core engine: cargo build -p trustfall. Run the demo: cargo run -p demo-hytradboi. For Python: pip install pytrustfall or build from source with maturin develop -m pytrustfall.

Daily commands: Development: cargo build && cargo test (runs entire workspace). Run demo: cargo run -p demo-hytradboi. Build WASM: wasm-pack build trustfall_wasm --target web. Test Python bindings: maturin develop -m pytrustfall && python -c "import trustfall; ...". Run docs locally: cd docs && npm install && npm start (Hugo/Node setup inferred from docs/.gitignore).

• trustfall_core/src/lib.rs — Core query engine implementation; entry point for all query execution logic and the public API surface.
• trustfall/src/lib.rs — Main crate exports; defines the public interface that users interact with for schema definition and query execution.
• trustfall_derive/src/lib.rs — Derive macro implementation for auto-generating adapter boilerplate; critical for reducing user friction when implementing adapters.
• trustfall_core/src/ir/mod.rs — Intermediate representation structures that model parsed queries and schemas; fundamental to query compilation and optimization.
• Cargo.toml — Workspace configuration defining all member crates, dependencies, and versioning strategy across Rust, Python, and WASM targets.
• demo-hytradboi/src/adapter.rs — Reference implementation showing how to build a multi-source adapter (GitHub + HackerNews); essential learning resource for new contributors.
• docs/docs/getting_started/index.md — User-facing documentation entry point explaining core concepts and first-time setup; shapes how developers learn the framework.

Add a new data source adapter

1. Define GraphQL schema types for your data source (demo-hytradboi/schema.graphql)
2. Run cargo run --bin trustfall_stubgen -- --schema-path your_schema.graphql --output-path src/adapter.rs to generate boilerplate (trustfall_stubgen/src/main.rs)
3. Implement the Adapter trait by filling in vertex resolution and edge traversal methods (trustfall/src/lib.rs)
4. Reference demo-hytradboi/src/adapter.rs as a working example for batching, pagination, and API calls (demo-hytradboi/src/adapter.rs)
5. Add integration tests to trustfall_testbin/src to verify query correctness against your adapter (trustfall_testbin/src)

Add a new query language feature

1. Define the AST node structure in trustfall_core/src/parser/grammar.rs (trustfall_core/src/parser)
2. Add parsing rules to handle the new syntax (using async-graphql-parser) (trustfall_core/src/parser)
3. Transform AST to IR in trustfall_core/src/ir/mod.rs (trustfall_core/src/ir/mod.rs)
4. Implement execution logic in trustfall_core/src/interpreter/mod.rs (trustfall_core/src/interpreter)
5. Add documentation in docs/docs/language_reference/ and update example queries in experiments/browser_based_querying/example_queries (docs/docs/language_reference/index.md)

Expose Trustfall to a new platform (e.g., Node.js, mobile)

1. Create a new crate in the workspace (e.g., trustfall_nodejs) or add bindings under a new module (Cargo.toml)
2. Study pytrustfall/src/lib.rs to understand the pattern for wrapping Rust APIs in Python; apply similar approach (pytrustfall/src)
3. Define public types and query execution functions that match your target platform's conventions (trustfall/src/lib.rs)
4. Add CI/CD workflow (e.g., .github/workflows/publish-nodejs.yml) to build and publish bindings automatically (.github/workflows/publish-python.yml)

Improve query performance or add optimization

1. Study the IR transformation pipeline in trustfall_core/src/ir/mod.rs to understand current optimizations (trustfall_core/src/ir/mod.rs)
2. Implement new optimization passes (e.g., filter pushdown, projection elimination) in trustfall_core/src/interpreter (trustfall_core/src/interpreter)
3. Add benchmark tests to trustfall_testbin/src to measure improvement (trustfall_testbin/src)
4. Update docs if the optimization affects user-visible behavior or performance characteristics (docs/docs/language_reference/index.md)

• Rust + async/await — Enables efficient concurrent execution of multiple adapter calls; compile-time safety reduces adapter implementation bugs; performance critical for cross-API queries.
• GraphQL (query syntax + schema language) — Widely understood by developers; schema-driven approach forces adapters to declare capabilities upfront; enables schema validation and optimization.
• Procedural macros (derive) — Eliminates boilerplate adapter code; reduces time-to-value for new data sources; maintains type safety through compile-time codegen.
• PyO3 + WASM — Extends reach to Python and browser ecosystems without rewriting core logic; leverages Rust's performance across all platforms.
• async-graphql-parser — Avoids writing a custom GraphQL parser; maintains compatibility with standard GraphQL; reduces maintenance burden.

• Schema-required (schema.graphql must be provided by adapter implementer)

  • Why: Enables static optimization, type safety, and schema validation; user understands capabilities upfront.
  • Consequence: Slightly higher upfront cost for new adapters; cannot dynamically discover schema at runtime like GraphQL introspection.

• IR-based compilation before execution

  • Why: Allows multi-pass optimizations (filter pushdown, unused field elimination); validates query against schema once.
  • Consequence: Additional latency for first query execution; more complex architecture than direct AST interpretation.

• Adapter trait requires batching/pagination strategy (implementer decides)

  • Why: Prevents naive N+1 queries; shifts responsibility to adapter author who understands their API's constraints.
  • Consequence: More complex adapter code; some adapters may not support efficient batching (e.g., rate-limited single-item APIs).

• Async execution model (tokio runtime)

  • Why: Allows parallel execution of independent vertex resolutions; efficient I/
  • Consequence: undefined

WASM builds require wasm-pack and wasm-opt; the CI sets up Node.js separately for WASM tooling (see .github/workflows/ci.yml). Python bindings depend on PyO3 and maturin; building from source requires Python dev headers. The monorepo uses workspace.dependencies; bumping workspace versions can trigger cascading rebuilds across all 8 members. Example queries in demo-hytradboi/example_queries/ are .ron format, not JSON—requires ron crate to parse. The schema is strict; custom adapters must implement the Adapter trait exactly (see trustfall_core/src/interpreter/mod.rs), or compilation fails with trait bounds errors.

• GraphQL Schema & Query Language — Trustfall uses GraphQL as the lingua franca for queries; understanding the schema (types, fields, directives like @fold, @filter, @output) is essential to writing queries and defining adapters
• Query Compilation & Planning — Trustfall compiles GraphQL into an optimized execution plan before running; understanding the compile phase (trustfall_core/src/compiler/) helps when debugging slow queries or writing efficient adapters
• Adapter Pattern (Iterator/Visitor) — Custom data sources must implement the Adapter trait with resolver functions that yield results; this is the core extension point for integrating new APIs or databases
• Recursive Query Execution (Depth-First Traversal) — Trustfall's @recurse directive enables traversing arbitrarily deep nested structures (e.g., comment threads); the interpreter executes these via depth-first traversal with a max-depth bound
• WASM/WebAssembly Module Compilation — The WASM build (trustfall_wasm) compiles Rust to JavaScript-runnable bytecode for the browser playground; understanding wasm-pack and module boundaries is crucial for maintaining the playground
• Fold Operations (Aggregation/Group-By) — The @fold directive in Trustfall queries performs aggregations (count, collect, filter) on nested result sets; it's the mechanism for transforming tree-shaped query results into scalar summaries
• Filter Transforms (Regex, Comparison Operators) — Trustfall supports client-side filtering with @filter(op: ...) directives (regex, string comparison, numeric ops); understanding these enables pushing filtering logic to the right layer (adapter vs. engine)

• graphql/graphql-core — Reference GraphQL specification and parser implementation; Trustfall uses async-graphql which targets this spec
• apollographql/apollo-client — Federated GraphQL client for multi-source data; Trustfall is server-side equivalent designed to unify query execution across adapters
• hasura/graphql-engine — Instant GraphQL APIs over databases; Trustfall solves the same multi-source problem but at the engine level for custom data sources
• datafusedev/datafuse — Cloud-native query engine supporting heterogeneous data sources; similar architecture philosophy of unified query planning over disparate sources
• obi1kenobi/ruler — Author's other project for generating GraphQL schemas from Rust types; pairs well with Trustfall for rapid adapter authoring

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Python bindings (pytrustfall) with real query execution

The repo has pytrustfall as a workspace member and Python publishing workflows, but the file structure shows no visible test files for the Python bindings. Currently, there are shell scripts like python_bindings_changed.sh that detect changes, but no corresponding integration test suite. This would validate that the Python API works end-to-end and catch regressions before publishing.

• [ ] Create pytrustfall/tests/ directory with integration test files
• [ ] Add tests that execute sample queries against the demo-hytradboi schema using the Python bindings
• [ ] Add Python test execution to .github/workflows/ci.yml using pytest or similar
• [ ] Reference the existing demo-hytradboi/example_queries/*.ron files as test fixtures
• [ ] Document how to run Python tests in pytrustfall/README.md (if it exists)

Add WASM binding tests and snapshot testing for schema compilation

The repo has trustfall_wasm and experiments/schemaless_wasm with a shell script wasm_pkg_changed.sh, but there's no visible test directory. Schema compilation is a critical path—snapshot tests would catch unintended changes to WASM bundle output, schema parsing, or error messages. This prevents silent regressions in the browser playground.

• [ ] Create trustfall_wasm/tests/ directory with snapshot tests using a tool like insta or similar
• [ ] Add tests that compile sample GraphQL schemas and snapshot the resulting WASM adapter structure
• [ ] Add tests for error cases (invalid schemas, missing types) to ensure helpful error messages
• [ ] Integrate snapshot tests into .github/workflows/ci.yml
• [ ] Update experiments/schemaless_wasm/ with similar test coverage

Create end-to-end documentation examples in docs/docs/getting_started/ for each major adapter type

The docs have a getting_started/ directory but only an index.md file is visible. The repo supports querying APIs, files, and databases, but there's no dedicated getting-started guide showing how to build a custom adapter for each pattern. The demo-hytradboi example is complex; simpler, focused examples would lower the barrier to entry.

• [ ] Create docs/docs/getting_started/adapters/ subdirectory
• [ ] Add api_adapter_example.md with a minimal example querying a public REST API (e.g., JSONPlaceholder)
• [ ] Add file_adapter_example.md showing how to query local JSON/YAML files
• [ ] Add custom_datasource_example.md showing a simple in-memory adapter
• [ ] Link these from docs/docs/getting_started/index.md and reference the full demo-hytradboi as an advanced example

• idea: Add missing documentation for the @fold operator in docs/docs/language_reference/querying/fold.md with concrete examples transforming list results (e.g., counting comments per user, grouping by type). Current file exists but is sparse.
• idea: Write integration tests for demo-hytradboi's pagers.rs module; currently only the adapter.rs has inline examples. Add tests/pager_integration_test.rs that verify pagination behavior against the HackerNews API stub.
• idea: Create a TypeScript/JavaScript example in the docs showing how to use trustfall via WASM in a Node.js environment (not just browser); right now trustfall_wasm is only documented for web. Add examples/wasm-nodejs-demo/ with a runnable example.

This Rust query engine project demonstrates good security practices overall. No critical vulnerabilities detected. The codebase uses modern dependency management with Cargo.lock and workspace organization. Key strengths: (1) Compiled language (Rust) with memory safety guarantees, (2) No obvious hardcoded credentials in visible configuration, (3) Proper use of GitHub security settings file. Minor concerns: (1) Shell scripts in CI/CD pipelines require review for injection risks, (2) Public API surface depends on external crates that should be monitored for vulnerabilities, (3) Dependency version strategy allows for updates but should be paired with regular security audits. Recommended immediate actions: Run 'cargo audit' in CI/CD, review all shell scripts for injection safety, and consider adding SBOM (Software Bill of Materials) generation for supply chain transparency.

• Low · Dependency Version Pinning Strategy — Cargo.toml - [workspace.dependencies]. The workspace dependencies use approximate version specifications (e.g., 'anyhow = "1.0.71"') rather than exact versions. While this enables security updates, it may introduce unexpected breaking changes in minor/patch versions of transitive dependencies. The Cargo.lock file mitigates this for binary crates but not for library crates. Fix: Consider evaluating critical dependencies with cargo audit regularly. The current strategy is acceptable for a library, but ensure CI/CD includes security scanning. Maintain Cargo.lock in version control for reproducible builds.
• Low · Workflow Script Shell Injection Risk — .github/workflows/*.sh files. Multiple shell scripts in .github/workflows (e.g., get_current_crate_version.sh, is_crate_version_already_uploaded.sh) are present. These scripts are commonly used in CI/CD pipelines and could be vulnerable to injection attacks if they process untrusted input from environment variables or workflow parameters without proper escaping. Fix: Review all shell scripts for proper input validation and quoting. Use 'set -euo pipefail' at the start of scripts. Avoid using unquoted variables. Consider migrating to GitHub Actions native steps where possible.
• Low · Public API Surface Security Dependencies — Cargo.toml - [workspace.dependencies]. The workspace declares several dependencies as part of the public API (anyhow, async-graphql-parser, serde, serde_json, thiserror, regex). Vulnerabilities in these dependencies directly impact all consumers of this library. The regex crate in particular has historically had ReDoS (Regular Expression Denial of Service) vulnerabilities. Fix: Enable 'cargo audit' in CI/CD pipeline. Maintain a security advisory process. Consider using cargo-deny to enforce dependency policies. Monitor regex crate releases closely for known ReDoS patterns in usage throughout the codebase.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.