CLI Reference
The SynDB CLI (syndb) provides command-line access to query execution, dataset management, federation administration, ETL pipelines, Kubernetes operations, and manuscript workflows.
Run the CLI with --help on any command to see available subcommands and options:
syndb --help
syndb <command> --help
Umbrella command migration
The supported operator surface is the syndb command. The former standalone
tools remain as compatibility binaries or Python entry points, but new scripts
should use these umbrella commands:
| Former entry point | Umbrella command | Runtime boundary |
|---|---|---|
syndb-export | syndb etl export fish1 only in an explicitly configured raw-stage deployment | Provider remains behind the umbrella CLI and must upload its artifact |
syndb-plot | syndb article ... | Python/TeX provider used by article workflows |
syndb-bench | syndb bench ... | Rust benchmark library |
syndb-ci | syndb ci ... | Rust CI dispatch library |
flight-workload | syndb bench workload flight ... | Rust benchmark library |
populate-cache | syndb article cache populate, resume, validate, build-figure-inputs | Rust article library |
synth-fixtures | syndb article cache fixtures, fixtures-check | Rust article library |
syndb-mcp / syndb-check | syndb mcp figures, check | Rust MCP libraries over stdio |
MCP clients in this repository start scripts/syndb-mcp.sh <mode>, which builds and execs
syndb mcp <mode>; see MCP Servers for the launcher contract and prerequisites.
The ETL CLI is fail-closed for workstation acquisition, transformation, validation, and import. Public sources must run on SynDB hub workers. A source may use local raw staging only when its registry policy and deployment configuration explicitly enable that path. The CAVE provider is reachable through the umbrella command only, and it enforces the same gate when invoked as a compatibility binary.
Global Options
| Option | Env Variable | Description |
|---|---|---|
--server-url <URL> | SYNDB_SERVER_URL | API base URL (default: https://api.syndb.xyz) |
--flight-url <URL> | SYNDB_FLIGHT_URL | Arrow Flight endpoint (default: https://syndb-flight.nrp-nautilus.io:50051) |
--flight-port <PORT> | SYNDB_FLIGHT_PORT | Arrow Flight port (default: 50051) |
-v, --verbose | — | Increase log verbosity: -v=info, -vv=debug, -vvv=trace (default: warn) |
auth — Authentication
Manage user sessions and credentials.
syndb auth register native --email user@example.com # Register with email/password
syndb auth login native --email user@example.com # Log in and store token
syndb auth login orcid # Associate ORCID (requires existing login)
syndb auth logout # Revoke session
syndb auth profile # Show current user profile
syndb auth service-login # Mint a smoke-grade service-account token
syndb auth show-token # Print stored token (for shell composition)
OAuth providers are also available: syndb auth login github, google, gitlab, cilogon.
query — Saved Queries and SyQL
Manage server-backed saved queries and execute SyQL statements.
syndb query list # List all saved queries
syndb query save -l "Mouse neurons" -t 0 \
--dataset-id <uuid> --column neuron_id --column cell_type
syndb query save-syql -l "All mouse" \
"FROM neurons WHERE species = 'mouse' LIMIT 1000"
syndb query show <id-or-label> # Show query details
syndb query update --id <uuid> -l "New label" # Update label/description
syndb query run --id <uuid> # Submit to job queue
syndb query status --id <uuid> # Check latest run status
syndb query delete --id <uuid> # Delete a saved query
syndb query exec "FROM neurons LIMIT 10" # Execute SyQL directly
syndb query explain "FROM neurons LIMIT 10" # Show logical plan without executing
syndb query exec submits the query as an async job. Results can be downloaded from the job queue via GET /v1/jobs/{id}/result (Arrow IPC format).
Table IDs for query save --table
| ID | Table |
|---|---|
| 0 | Neuron |
| 1 | NeuronRelation |
| 2 | Axon |
| 3 | Dendrite |
| 4 | Synapse |
| 5 | DendriticSpine |
| 6 | EndoplasmicReticulum |
| 7 | Mitochondria |
| 8 | PreSynapticTerminal |
| 9 | Vesicle |
| 10 | Mesh |
| 11 | SwbSkeleton |
federation — Federation Node Operations
Register, sync, and test federation nodes. Requires the federation feature.
syndb federation init --cluster-name my-lab \
--clickhouse-endpoint clickhouse.mylab.edu \
--federation-password "$SYNDB_FEDERATION_PASSWORD"
syndb federation status # Show federation status
syndb federation sync-schema --dry-run # Preview schema sync (remove --dry-run to apply)
syndb federation test # Run federation end-to-end tests
syndb federation clusters # List registered clusters
syndb federation logout # Revoke federation session
See Node Setup for detailed instructions.
migrate — ClickHouse Schema and Data Migrations
Manage ClickHouse schema layout and materialized-view backfills. Requires the etl feature.
syndb migrate ensure-schema --database syndb \
--layout distributed-staged --cluster my-chi # Ensure schema exists in requested layout
syndb migrate mv-backfill --database syndb # Backfill MV target tables from existing base rows
syndb migrate provenance-events-to-distributed \
--database syndb --cluster my-chi --namespace syndb \
--chi-name syndb-chi # Convert MergeTree tables to Replicated+Distributed
etl — Connectomics Dataset Import Pipeline
Download, validate, prepare, and import connectomics datasets. Requires the etl feature.
syndb etl <dataset> download # Download from source (where supported)
syndb etl <dataset> validate # Validate downloaded data
syndb etl <dataset> import --data-dir <path> \
--table neurons --dataset-id <uuid> # Import into SynDB
Dataset keys
| Dataset | Key | Source |
|---|---|---|
| FlyWire | flywire | Zenodo 783 (credential-free) |
| Hemibrain | hemibrain | Google Cloud Storage |
| MANC | manc | Google Cloud Storage (Feather) |
| MICrONS | microns | BossDB / GCS |
| H01 | h01 | CAVE global.brain-wire-test.org (h01_c3_flat) |
| Optic Lobe | optic-lobe | Google Cloud Storage |
| Male CNS | male-cns | neuPrint inputs (GCS) |
| BANC | banc | Codex-backed (Parquet) |
| Spine Morphometry | spine-morphometry | Zenodo / Columbia Commons (use --source) |
| C. elegans Herm. | celegans | GitHub (Cook et al. 2019) |
| C. elegans Pharynx | celegans-pharynx | GitHub (Cook et al. 2020) |
| C. elegans Male | celegans-male | GitHub (WormWiring) |
| C. elegans Dauer | celegans-dauer | Google Sheets (Yim et al. 2024) |
| Varshney | varshney | GitHub (Varshney et al. 2011) |
| White Whole Worm | white-whole | GitHub (White et al. 1986) |
| WormNeuroAtlas | worm-neuro-atlas | GitHub |
| Drosophila Larval | larval | GitHub (Winding et al. 2023) |
| Drosophila L1 nerve cord | gerhard2017-l1 | GitHub (Gerhard et al. 2017) |
| Drosophila L3 nerve cord | gerhard2017-l3 | GitHub (Gerhard et al. 2017) |
| P. pacificus amphid | ppacificus-amphid | eLife CDN (Hong et al. 2019) |
| L2/3 cortex dendrites (human, macaque, mouse) | loomba2022-human, loomba2022-macaque, loomba2022-mouse | Edmond (Loomba et al. 2022) |
| Zebrafish olfactory bulb | wanner2016 | Zenodo 58985 (Wanner et al. 2016, CC BY-NC) |
| Allen Cell Types | allen-cell-types | Allen Institute API |
| NeuroMorpho | neuromorpho | NeuroMorpho.org REST API |
| Witvliet Developmental | witvliet | GitHub (Witvliet et al. 2021) |
| Ciona | ciona | eLife CDN (Ryan et al. 2016) |
| Platynereis | platynereis | GitHub (Verasztó et al. 2024) |
| Medulla 7-Column | medulla-7col | Zenodo + Janelia |
| FANC | fanc | CAVE global.daf-apis.com (fanc_production_mar2021) |
| Fish1 | fish1 | CAVE global.brain-wire-test.org (fish1_full) |
| Songbird | songbird | SyConn REST API |
Utility commands
syndb etl seed --dataset-label "Songbird Basal Ganglia (Rother et al. 2025)" \
# Seed one reviewed registry dataset
syndb etl seed --all # Explicitly seed every registry dataset
syndb etl registry check # Validate registry integrity
syndb etl status -n syndb # Show ETL pipeline status from Kubernetes
syndb etl update-all # Update all datasets (skip unchanged, reimport changed)
CAVE credentials
CAVE-backed pipelines (Fish1, H01, FANC, and the MICrONS prepare job) read API
keys from ~/.cloudvolume/secrets/<host>-cave-secret.json, the same store
caveclient uses. Keys do not expire, so an existing key can mint a replacement
without a browser:
syndb etl cave status # Check stored keys, key validity and datastack access
syndb etl cave status --json --cluster # JSON report, including syndb-api-secrets.cave_token
syndb etl cave login --server https://global.daf-apis.com # Browser + paste, once per host
syndb etl cave rotate --server https://global.daf-apis.com # Mint and store a replacement key
syndb etl cave rotate --server https://global.daf-apis.com --deploy
syndb etl cave deploy --server https://global.daf-apis.com # Push the stored key to sops + Secret
| Pipeline | Server | Datastack |
|---|---|---|
| fish1 | https://global.brain-wire-test.org | fish1_full |
| h01 | https://global.brain-wire-test.org | h01_c3_flat |
| fanc | https://global.daf-apis.com | fanc_production_mar2021 |
| microns (prepare) | https://global.daf-apis.com | minnie65_public |
status exits non-zero when a row needs attention and prints a concrete remedy
for each failure. rotate revokes the old key only after the new key is
verified and every requested write has succeeded; --keep-old keeps it.
--deploy and deploy write syndb-api-secrets.stringData.cave_token in
infrastructure/helm/nautilus/k8s-secrets.yaml and patch the live Secret, so
they only accept the global.daf-apis.com key that prepare jobs use.
data — Dataset Management
Create, prepare, upload, download, and search datasets. Requires the dataset feature.
syndb data new -l "Example" --animal "Mus musculus" \
--microscopy EM -t 0 --brain-structure hippocampus # Create a new dataset
syndb data prepare --input-dir raw --output-dir prepared
syndb data validate --input-dir prepared
syndb data upload --input-dir prepared --dataset-id <uuid>
syndb data download --dataset-id <uuid> --output-dir download_dir
syndb data mesh-upload --dataset-id <uuid> --input-dir meshes
syndb data swb-upload --dataset-id <uuid> --input-dir swb
syndb data delete --dataset-id <uuid>
syndb data search reconcile --dry-run # Rebuild Meilisearch index (omit --dry-run to apply)
syndb data cache-tags # Cache tag metadata
syndb data gen-test-data --output-dir tmp/test-data # Generate test data fixtures
ops — Operations
Infrastructure operations: Kubernetes, backups, capacity planning, game-day drills, and health monitoring.
ops k8s — Kubernetes administration
syndb ops k8s etl status # Show ETL job status on K8s
syndb ops k8s etl report # Show detailed error report for failed jobs
syndb ops k8s etl watch # Watch ETL jobs until terminal
syndb ops k8s etl retry -y # Delete failed jobs for retry
syndb ops k8s etl cleanup -y # Delete completed and failed jobs
syndb ops k8s etl reset --all # Delete all ETL jobs
syndb ops k8s etl redeploy <pipeline> # Delete selected immutable jobs
syndb ops k8s nautilus apply # Recreate jobs after retry/redeploy
syndb ops k8s etl clickhouse-forward # Port-forward ClickHouse to localhost:18123
syndb ops k8s etl s3-clear <prefix> -y # Clear an S3 prefix used by ETL jobs
syndb ops k8s preflight run # Run storage-tiering cutover preflight checks
syndb ops k8s report --json # Read-only diagnostics as checks[]
syndb ops k8s report --only etl --only chi --exclude node
ops k8s report emits one checks[] entry per finding with id, status
(ok|warn|fail|unknown), severity (info|warning|critical|unknown),
evidence, remediation and actionable. It exits 0 when nothing
actionable failed, 1 when an actionable failure is present, and 2 for
invalid arguments. Expected ClickHouse sizing comes from the rendered release
manifest (helm get manifest), never from a hardcoded CPU value; provider
nodes that no SynDB pod uses are reported as observations, never as SynDB
failures.
CAVE credentials are managed with syndb etl cave (see
CAVE credentials); the old cave-token-deploy helper is
gone.
Production builds do not imply the Helm apply after retry or redeploy.
Run the explicit nautilus apply step after reviewing the deletion result.
Additional k8s subcommands: secrets, sites, nautilus, nautilus-etl, and various validate-* / migrate-* / cutover-* / list-* / rebuild-* / cleanup-* / discard-* / finalize-* / inspect-* helpers for ClickHouse layout and Flight staging management. Run syndb ops k8s etl --help for the full list.
ops backup — ClickHouse backup
syndb ops backup trigger --namespace syndb \
--cronjob syndb-backup --yes # Create a one-off backup Job
syndb ops backup verify --namespace syndb # Read-only pre-migration verification
syndb ops backup restore-drill --help # Inspect the suspended drill interface
Do not run the published restore-drill command against Nautilus until
the restore-drill blocker is cleared: its
current database lifecycle still uses ON CLUSTER instead of direct per-pod
Atomic operations.
ops snapshot — ClickHouse VolumeSnapshots
syndb ops snapshot create --namespace syndb \
--selector app=clickhouse --snapshot-class csi-snap # Create PVC snapshots
syndb ops snapshot prune --namespace syndb \
--selector app=clickhouse --retention-hours 168 # Prune snapshots older than retention
ops capacity — Capacity forecasting
syndb ops capacity report --out capacity.json # Write shard-capacity forecast
syndb ops capacity provision-budgets # Create dataset budget tables in ClickHouse
syndb ops capacity validate-budgets \
--manifest budget-manifest.yaml --evidence-dir evidence \
--check-postgres # Read-only source/UUID/evidence gate
syndb ops capacity apply-budgets \
--manifest budget-manifest.yaml --evidence-dir evidence \
--check-postgres --yes # Load one reviewed manifest
syndb ops capacity sync \
--check-postgres --yes # Generate and load safely
ops gameday — Operational game-day drills
syndb ops gameday run gd-a --report-dir reports/ # Run a specific drill scenario
Available scenarios: gd-a, gd-c, gd-d, gd-f.
ops cutover — CHI commissioning and cutover
syndb ops cutover schema-create # Create schema for a new CHI
syndb ops cutover populate # Hydrate per-shard data
syndb ops cutover parity # Run read-only parity probes
syndb ops cutover flip-serving # Flip deployments to new CH
syndb ops cutover decommission # Remove old CHI Helm release
ops health — Health monitoring
syndb ops health prom-export # One-shot Prometheus textfile export
syndb ops health serve --listen 0.0.0.0:9101 # In-cluster scrape target (ServiceMonitor)
syndb ops health probe --target api=http://syndb-api-service:80/health --json
syndb ops health digest --input health-latest.json --output digest.md
syndb ops health host-export --repo . --output-dir <textfile-dir>
Probes distinguish ok, slow (over the latency budget), failed (an HTTP
failure response) and unavailable (no connection or timeout), and always
bound the request with --timeout-ms. Metrics carry collector="in-cluster"
or collector="host" plus a collector_timestamp_seconds freshness sample.
ops helm-drift — Helm values snapshots
syndb ops helm-drift run # Capture latest Helm values and prune old snapshots
ops runbook — Runbook index
syndb ops runbook index --regen # Regenerate documentation/runbooks/INDEX.md
syndb ops runbook index --check # Check index is up-to-date
ops release — Release publication
Release publication is operator-run because it uses the operator’s signing key
and PyPI token. status is read-only and shows, for every CHANGELOG.md
version, the release: prepare X.Y.Z commit on origin/trunk, the vX.Y.Z
tag locally and on origin, and the GitHub release, plus the syndb-client
version against PyPI. Each missing item prints its next command.
syndb ops release status [--json]
syndb ops release publish --version X.Y.Z [--rev SHA] [--dry-run]
syndb ops release pypi --package syndb-client [--version-tag vX.Y.Z] [--dry-run]
publish resolves the single prepare commit (or --rev, which must be an
ancestor of origin/trunk), creates a signed annotated tag with the configured
signing key, verifies it, pushes only that tag, and creates the GitHub release
whose notes are that version’s CHANGELOG section. It refuses to move an existing
tag and skips steps that already completed.
pypi exports the tag (or origin/trunk) with git archive, builds
syndb-client in a tempdir, checks the wheel metadata and that the version is
unpublished, then uploads with uv publish. The token is read only from
UV_PUBLISH_TOKEN; it is never printed. --dry-run prints the commands and
notes without tagging, pushing, building, or uploading.
ops phase-e — Post-destructive consistency probe
syndb ops phase-e observe # Run one observation probe, persist to S3
syndb ops phase-e close # Aggregate all probes, write close.json
Requires the etl feature.
ops seed-datasets — DOI seeding
syndb ops seed-datasets --dry-run # Preview missing DOIs
syndb ops seed-datasets --from-cluster --namespace syndb # Seed DOIs from production cluster
Requires the etl feature.
article — Manuscript Workflows
Build, validate, and render the SynDB manuscript. The article commands resolve the project’s plot provider from the SynDB development or tools environment.
article archive — Zenodo archival
syndb article archive oauth login # Log in to Zenodo (OAuth)
syndb article archive deposition prepare # Create/update draft deposition
syndb article archive deposition reserve-doi # Reserve a DOI
syndb article archive deposition upload # Upload reproducibility archive
syndb article archive deposition publish # Publish a ready deposition
syndb article archive deposition list # List user depositions
syndb article archive doi # One-shot: prepare draft + reserve DOI
syndb article archive status # Show local OAuth/deposition status
article cache — Data cache
syndb article cache populate # Populate Parquet cache from Nautilus Flight
syndb article cache resume # Continue cache population (skip existing)
syndb article cache validate --figure CF04 # Validate production figure inputs
syndb article cache build-figure-inputs --figure all # Build figure input manifests
syndb article cache fixtures # Regenerate offline fixtures under article/figures-synthetic
syndb article cache fixtures --manifests # ...and their figure inputs there (never the evidence tree)
syndb article cache fixtures-check # Verify fixtures haven't drifted
article layout — Figure layout
syndb article layout solve # Solve all figure layout TOMLs
syndb article layout sync-sizes # Sync sizing constants into TeX fragments
syndb article layout sync-figures # Propagate figures.toml to layouts/panels/TeX
syndb article layout check # Validate figure registry consistency
article figure — Panel rendering
syndb article figure all # Export all panels, TikZ, composite figures
syndb article figure one 5 # Build CF05 end-to-end
syndb article figure panel CF01 A # Export a single panel as PNG
syndb article figure panels # Export matplotlib panels
syndb article figure tikz # Compile TikZ fragments
syndb article figure composites # Compile composite SVG/PNG outputs
Use --synthetic for synthetic fixtures, --skip-visual-rubric for fast local loops.
article graph — ETL graph figures
syndb article graph spec # Generate production ETL graph spec
syndb article graph render # Generate CF12 ETL graph panel SVGs
syndb article graph precompute # Run graph precompute against Nautilus
syndb article graph precompute-manc-k8 # Run MANC precompute as in-cluster K8s job
article build — Manuscript compilation
syndb article build rebuild # Sync sizes, export figures, compile PDF
syndb article build compile # Compile manuscript to PDF only
syndb article build clean # Remove LaTeX auxiliary files
syndb article build preflight # Validate cache, benchmark, figure contracts
syndb article build cf08-ultrastructure-preflight # Check live CF08 ultrastructure inputs
stack — Local Development Stack
Manage the local Docker Compose stack. Requires the dev feature.
syndb stack prepare # Build local Docker images
syndb stack prepare --fast # Use cached cargo builds
syndb stack up # Start the compose stack
syndb stack ensure # Start if not already running
syndb stack down # Stop the compose stack
syndb stack clean # Stop and remove volumes/orphans
syndb stack logs [service] # Stream compose logs
syndb stack federation up # Start federation compose profile
syndb stack federation down # Stop federation compose profile
syndb stack wait clickhouse --port 18123 # Wait for ClickHouse to be ready
syndb stack wait flight --port 50051 # Wait for Flight to be ready
test — Test Shortcuts
Run test suites against local or production infrastructure.
For focused checkout-based UI work, use the lightweight Just recipes in the
full development shell (nix develop) instead of bootstrapping the full syndb
CLI:
nix develop -c just ui-preflight
nix develop -c just ui-check
nix develop -c just ui-browser TARGET
nix develop -c just ui-visual VISUAL_TARGET
Browser targets must be the integrated local Rust consumer targets; the
existing syndb test e2e below remains the real-stack workflow. See
Checkout-Based UI Tests for authorization blockers,
frozen bundle/run inputs, evidence schema, and direct diagnostic commands.
syndb test rust # Run workspace tests with nextest
syndb test all # Run Rust tests and browser contracts
syndb test e2e # Run Rust WebDriver browser contracts
syndb test integration # Run DB-dependent integration tests
syndb test stack # Run self-contained DB integration tests
syndb test meilisearch-local # Local Meilisearch reconcile + API smoke
syndb test federation # Federation end-to-end tests
syndb test helm # Verify Helm templates render correctly
syndb test production # Production integrity tests against Nautilus CH
syndb test queryfabric # Standalone QueryFabric release gate
syndb test queryfabric-full # Full SynDB-to-QueryFabric validation
syndb test queryfabric-rollout # Validate PostgreSQL DB for QueryFabric-only startup
graph-precompute — Batch Graph Analysis
Pre-compute graph metrics into ClickHouse materialized tables. Requires the graph-precompute feature.
syndb graph-precompute --dataset flywire # Compute metrics for one dataset
syndb graph-precompute --dataset flywire --dataset manc # Compute for multiple datasets
syndb graph-precompute nautilus-local # Run locally against Nautilus (port-forwards)
syndb graph-precompute nautilus-job --dataset manc \
--image-tag 0.10.71 # Run as in-cluster K8s Job
bench — Benchmarking
Performance testing suite for API and federation queries. Requires the bench feature.
Benchmark commands are dispatched through the umbrella CLI. Run syndb bench --help for available subcommands.
ci — CI/CD Helpers
Internal build, test, and image automation helpers. Requires the ci feature.
CI commands are dispatched through the umbrella CLI. Run syndb ci --help for available subcommands.
dev — Developer Utilities
Development workflow helpers. Requires the dev feature.
syndb dev sync-versions # Sync image versions from versions.nix into .env
syndb dev upgrade # Upgrade Cargo, uv, and infrastructure versions
syndb dev nix-check # Run all Nix flake checks
syndb dev docs-build-rapid # Trigger site/docs GitHub workflow against rapid
completions — Shell Completions
syndb completions bash > ~/.local/share/bash-completion/completions/syndb
syndb completions zsh > ~/.zfunc/_syndb
syndb completions fish > ~/.config/fish/completions/syndb.fish
Checkout-Based UI Tests
The Just recipes are authoritative for focused UI checks. They call
scripts/ui-tests/run.sh directly, not the full syndb CLI. They use the
existing default Harbor development shell and real Git history. They do not
start Compose, deploy services, alter dependencies, authorize direnv, change
compiler overrides, or weaken the frozen BR-01 payload checks.
Environment
Run from the checkout root in the full development shell (nix develop). The
lean .#dev shell that direnv can load lacks dx, wasm-bindgen, and
chromium:
nix develop -c just ui-preflight
nix develop -c just ui-check
If direnv says .envrc is blocked, stop for operator approval of that exact
checkout. Approval of another worktree is not approval of this one. No recipe
runs direnv allow, falls back to a cached shell, or edits the existing
Python/uv shell hook. A shell-startup failure occurs before these recipes and
must be diagnosed separately.
For the isolated parallel workers, load the approved environment first, source
the coordinator’s worker-env.sh from your own checkout, and set
SYNDB_UI_TEST_BASE_REVISION to the frozen BASE from the handoff. Do not point
output variables at another worker’s directories. Standalone runs default BASE
to HEAD; parallel runs require it explicitly.
ui-preflight audits the full environment. ui-check checks only the tools it
uses, so missing browser executables do not block native/WASM compilation.
Expected Dioxus and wasm-bindgen versions come from Cargo metadata/Cargo.lock.
The selected rustc must have actual wasm32-unknown-unknown core libraries.
Chromium and Chromedriver must share a major version; this is a prerequisite,
not proof of successful session negotiation (owned by the Rust support).
Both nested checkouts must match the recorded HEAD gitlinks and be internally clean. Ordinary dirty application files and linked worktrees are supported. Both frozen manifest revisions must resolve as exact local commits. The recipes never fetch history or reconcile flake/Cargo pins automatically.
Gates
ui-check runs, in order:
- Scoped Rust formatting.
- Locked, explicit-server
syndb-uitests. - Discovery and execution of the canonical test that reproduces both frozen workbench editions and the hosted access contract.
- Locked, explicit-web compilation for
wasm32-unknown-unknown. - Scoped server Clippy, including test targets, with warnings denied.
No command combines server/web using --all-features. Cargo/DX operations are
offline as well as locked: missing dependency materialization is a blocker, not
permission for a recipe to download or rewrite pins. Resolve that separately
under the normal dependency/Canix policy, then rerun.
Browser and Visual Runs
# TARGET is an actual integrated Rust test target supplied by the consumer owner.
nix develop -c just ui-browser TARGET
nix develop -c just ui-visual VISUAL_TARGET
These are separate invocations, not aliases for the real-stack E2E workflow.
The old browser_contract target remains reserved for syndb test e2e and is
not accepted here. The local consumer target must use Agent 4’s support module.
Missing targets/support fail explicitly; the runner does not create stubs.
Each invocation sequentially builds the current fullstack UI into a fresh per-run Cargo/DX
output directory and discovers the emitted server plus adjacent public
there. It does not assume the conventional DX layout. Missing, ambiguous,
non-executable, symlink-containing, or WASM-less bundles fail. A failed build
cannot select an older bundle. This intentionally forgoes cross-run Cargo
artifact reuse for DX output; Harbor’s managed compiler cache remains intact.
The producer copies the verified bundle into a read-only directory, writes its
manifest, discovers the requested Rust tests, then runs them with
--include-ignored --test-threads=1. An empty target fails. Visual mode also
requires a screenshot artifact; the visual target owns matrix completeness.
Capturing PNGs is not visual approval.
Only the frozen inputs are passed from runner to runtime support:
SYNDB_UI_TEST_BUNDLE_DIR: absolute producer-verified directory containingserver,public, andbundle-manifest.json.SYNDB_UI_TEST_RUN_DIR: absolute newly created empty scenario-artifact root.
Agent 4 owns all UI/API/WebDriver processes, browser profiles, strict fixture expectations, cleanup, and runtime compatibility. This runner does not launch any runtime services. Agents 5-6 supply distinct test targets and assertions.
Evidence and Manifest Schema
Every invocation prints its evidence directory. Default location:
target/ui-tests/evidence/MODE.RANDOM; parallel workers use their own
SYNDB_UI_WORKER_STATE/evidence. Logs, bundles and failures are retained.
result.json contains mode, original exit code, error text, source stability,
source identity, tool versions/paths, and stage command/results. Each command
has separate stdout/stderr and combined logs. Source identity includes BASE,
candidate commit, dirty state, a SHA-256 fingerprint of Git/index/worktree and
untracked source contents including nested repositories, Cargo/flake lock
hashes, and recorded/actual nested revisions. Raw source diffs and environment
contents are not written into evidence.
bundle-manifest.json schema version 1:
schema_version: 1
source: {base, revision, fingerprint, dirty, lock_hashes, nested}
tools: {tool_name: {path, version}, ...}
files: [{path: "server" | "public/<relative-path>", sha256}, ...]
build: {stage: "fullstack-build", argv: [...], exit_code: 0}
The manifest itself is not included in files. Agent 4 must revalidate all
listed hashes and reject missing/extra assets before starting the runtime.
Source stability is checked before/after every command and on exit. Detected
change invalidates the evidence and stops subsequent stages (exit 75 if no
earlier command failed). The original nonzero command status is preserved.
Do not edit a checkout while its checks run: boundary fingerprints are not a
filesystem transaction and cannot detect a transient edit restored entirely
between observations. Rebuild after integrating application fixes.
Direct Diagnosis
Within the approved environment, the corresponding commands are:
cargo metadata --locked --offline --no-deps --format-version 1
rustc --print target-libdir --target wasm32-unknown-unknown
cargo fmt -p syndb-ui --check
cargo test --locked --offline -p syndb-ui --no-default-features --features server
cargo test --locked --offline -p syndb-review-workbench --test workbench pinned_editions_and_hosted_contract_reproduce_committed_files -- --exact
cargo build --locked --offline -p syndb-ui --no-default-features --features web --target wasm32-unknown-unknown
cargo clippy --locked --offline -p syndb-ui --no-default-features --features server --all-targets --no-deps -- -D warnings
Never replace missing BR-01 history with HEAD or disable its manifest/byte checks. Report blocked checks separately from failures and passes. Do not declare the UI migration verified from recipe fixtures or compilation alone.
Runner Regression Tests
just ui-runner-test
The Bash fixture suite uses real temporary Git clones/history and explicitly mocked compiler/browser commands. It checks command ordering, version/history failures, missing WASM tooling, exact exit status propagation, source mutation, fresh bundle discovery, stale-input rejection, symlink rejection, nonempty test selection, and visual capture requirements. It does not compile or render the UI and is not a replacement for the gates above. Its artifacts are retained beneath the worker evidence directory.
Ownership and Design Authority
Tartan UI owns shared presentation: ProductShell, Panel, Field,
FeedbackBanner, NavigationList, ThemeToggle, the shared stylesheet, and
the --tartan-* tokens. SynDB owns product behavior: routes, forms, auth/BFF,
theme persistence and document policy, plus the one-way token remap and
intentional .tartan-* selector overrides in
crates/services/ui-dioxus/public/site.css. QueryFabric owns the SyQL editor
component. Tartan upgrades must be checked against both token compatibility and
the local selector overrides.
OpenPencil is a code-derived design reference, not the implementation source.
The Dioxus UI renders first; the importer captures it into .fig artifacts for
review and regression comparison. There is no verified reverse path from edited
.fig files back into code. The accepted reference is the promoted output
described by .openpencil-import/REPORT.md; .openpencil-import.run/ trees
are historical evidence. New contract runs write to
target/openpencil-contracts/ via openpencil/run-contracts.sh. Capture
success and visual approval are separate outcomes: a passing capture means the
import/export/verification gates held, not that a human approved the design.
OpenPencil Tool Contract
All capture paths (direct runners, the aggregate run-contracts.sh, and the
Nautilus candidate capture) resolve the same single tool bundle via
openpencil/resolve-tools.sh: explicit env, else the vendored repo copy in
openpencil/tools/ (byte-identical to skill dioxus-openpencil-import
0.2.0 including the Node shim and license; see PROVENANCE with per-file
hashes; resync deliberately, never drift), else the legacy skill checkout.
Importer, verifier, comparator, and Node shim must stay siblings (verifier
derived from the importer directory — never mix sources). The OpenPencil
executable is selected via OPENPENCIL_COMMAND
(default: the hermetic Nix openpencil package in the devshell, falling back
to npx --yes @open-pencil/cli@0.14.0 outside it) and shared by capture,
preparation, and verification; the artifact
gate checks executable identity plus the recorded detectedVersion and
capability booleans in provenance/openpencil-capabilities.json against
openpencil/profiles.toml, not the npm command spelling. The importer and
verifier run in their pinned PEP 723 environments (playwright==1.61.0,
Pillow==12.3.0); synthetic browser tests provision the same Playwright via
uv run --with. Missing tools fail before any build or service starts.