⚠️ AI-Agent-Only Repository

This repo is planned, maintained, and managed exclusively by AI Agents. Slop issues, rough edges, and AI artifacts are expected and intentionally present as part of an HITL-less / minimized AI-DD metaproject focused on learning, refining, and brute-force training both the agents and the human operator. Bug reports and contributions are still welcome, but please expect AI-generated code, comments, and documentation throughout.

Work State

Field	Value
Last commit	2026-06-08 18:49:21 -0700
Open issues	unknown (GitHub API rate-limited)
Open PRs	unknown (GitHub API rate-limited)
Focus	Data-layer crates and SurrealDB integration

Progress: ████████░░ 80%

Work state: ACTIVE · Progress: ██████░░░░ 55% Rust data-layer crates (storage/surreal bridge); on main, audits landing · updated 2026-06-02

Pinned references (Phenotype-org)

• MSRV: see rust-toolchain.toml
• cargo-deny config: see deny.toml
• cargo-audit: rustsec/audit-check@v2 weekly
• Branch protection: 1 reviewer required, no force-push
• Authority: phenotype-org-governance/SUPERSEDED.md

PhenoData — Data Layer Workspace

State

Progress: [██████░░░░] 55% — Rust data-layer crates on main, audits landing.

Updated 2026-06-08 — audit pass.

Status: maintenance

Data-related crates for the Pheno ecosystem.

Docs shell: docs/ is a VitePress site published through GitHub Pages.

Crates

This workspace currently ships 3 crates (verified against Cargo.toml):

Crate	Description
surreal-bridge	SurrealDB embedded integration (skill/embedding storage)
pg-bridge	PostgreSQL with pgvector for vector search
pheno-query	Unified query planner across data stores

Workspace layout

phenoData/
├── Cargo.toml              # Workspace manifest (3 members, resolver = "3")
├── Cargo.lock              # Locked dep graph (committed)
├── justfile / Justfile     # Phenotype-org standard recipes
├── tarpaulin.toml          # Coverage threshold baseline (see Coverage)
├── deny.toml               # cargo-deny config (licenses, advisories, sources)
├── rust-toolchain.toml     # Stable channel + rustfmt + clippy
├── package.json            # VitePress docs sidecar
├── bun.lock                # Locked docs deps
├── docs/                   # VitePress site (published via GitHub Pages)
├── crates/
│   ├── surreal-bridge/     # SurrealDB embedded integration
│   ├── pg-bridge/          # PostgreSQL + pgvector
│   └── pheno-query/        # Unified query planner
├── .github/
│   ├── workflows/          # CI: ci, coverage, gitleaks, trufflehog, codeql-rust, ...
│   └── dependabot.yml      # cargo + npm + github-actions (weekly, grouped)
└── worklogs/               # Per-session agent work logs

Requirements

• Rust 1.84+ — workspace uses resolver = "3" (stabilized in 1.84).
• PostgreSQL 14+ with pgvector — required for pg-bridge. Install:

  # macOS
  brew install postgresql@16 pgvector
  # Debian/Ubuntu
  sudo apt install postgresql-16 postgresql-16-pgvector

  Then enable the extension in your database:

  CREATE EXTENSION IF NOT EXISTS vector;

• SurrealDB — surreal-bridge runs SurrealDB embedded; no external server required.

Usage

Add the crate(s) you need to your Cargo.toml:

[dependencies]
surreal-bridge = { path = "../phenoData/crates/surreal-bridge" }
pg-bridge      = { path = "../phenoData/crates/pg-bridge" }
pheno-query    = { path = "../phenoData/crates/pheno-query" }

First build compiles SurrealDB and pgvector bindings — expect a longer initial cargo build.

Build & Test

cargo build --workspace
cargo test  --workspace
cargo clippy --workspace -- -D warnings

Test

The full test sweep runs the ci.yml job on every push and pull request:

# Local equivalent
just test
cargo test --workspace

pg-bridge integration tests skip cleanly when PostgreSQL with pgvector is not reachable (see AGENTS.md agent guardrails). No external services are required for the default test path.

Coverage

Coverage is produced by cargo-llvm-cov in the coverage.yml CI job and uploaded to Codecov. The baseline threshold (60% line coverage) is mirrored between tarpaulin.toml and the --fail-under-lines flag in CI.

# Install once
cargo install cargo-llvm-cov --locked

# Local equivalent of CI
just coverage           # HTML report at target/llvm-cov/html/index.html
just coverage-lcov      # lcov.info at repo root (CI artifact)

To bypass the threshold locally, drop the --fail-under-lines flag from the recipe — but keep CI strict.

Integration smoke tests live in crates/smoke-tests/tests/smoke.rs and are part of the workspace test run.

Docs

bun install
bun run docs:build

The Pages workflow builds with GITHUB_PAGES=true, which serves the site under the /phenoData/ GitHub Pages base path.

Examples

Standalone examples are not yet published. See each crate's src/ and inline tests (#[cfg(test)] modules) for current usage patterns. Tracking issue for examples will be opened once the public API stabilizes.

License

Dual-licensed under MIT or Apache-2.0 — see LICENSE-MIT and LICENSE-APACHE. The repository also carries the org-standard LICENSE file.

Description

Phenotype data-layer workspace — Rust crates for surreal-bridge (SurrealDB embedded integration), pg-bridge (PostgreSQL + pgvector), and pheno-query (unified query planner across data stores).

Install

Requirements: Rust 1.84+, PostgreSQL 14+ with pgvector for pg-bridge (see ## Requirements above). Add the crates you need to your Cargo.toml:

[dependencies]
surreal-bridge = { path = "../phenoData/crates/surreal-bridge" }
pg-bridge      = { path = "../phenoData/crates/pg-bridge" }
pheno-query    = { path = "../phenoData/crates/pheno-query" }

First build compiles SurrealDB + pgvector bindings — expect a longer initial cargo build.

Contributing

PRs welcome. See CONTRIBUTING.md. New crates go in crates/ and join the workspace via Cargo.toml. Schema changes for pg-bridge need a matching pgvector migration in the crate's migrations/ dir.