Imported from JiaJunDeng5930/recsql (
AGENTS.md). Install upstream withnpx skills add JiaJunDeng5930/recsql. Copyright stays with the author.
RecSQL Agent Notes
RecSQL is a Rust 2024 workspace. The root holds orchestration, policy, docs, tests, and config. Runtime implementation lives under crates/.
Package order:
recsql_corerecsql_protocolstorage_enginesql_tempreplicationsql_frontendnode_runtimesql_executormeta_controldata_storesql_gatewayrecsql_server
Dependency direction follows that order and the DAG in docs/design/00_project_scaffold.md. Add internal dependencies only along allowed edges. recsql_server/src/main.rs only delegates to recsql_server::run.
Public API work starts in the package's design document. Define state machines, failure model, durable formats, and external inputs before implementation. Use structured Result for external input, filesystem, network, and config failures. unsafe requires package design notes covering owner, safety preconditions, and tests.
When implementing a package, create or update its English README.md. It must list all public API exposed by the package, describe external usage, and document the full package state machine when the package owns runtime state.
Local branch integration uses rebase plus fast-forward merge. Configure the local repository with pull.rebase=true, branch.autosetuprebase=always, rebase.autoStash=true, merge.ff=only, and core.hooksPath=.githooks.
Run before commit:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo xtask agents-index check
cargo test --workspace --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-depsProject Index Workflow
- Update the index with
cargo xtask agents-index update. - Check whether the index is current with
cargo xtask agents-index check. - The index includes Git-tracked files. Git-ignored and untracked files are excluded.
- Index commands warn when an indexed directory has an unusually large number of direct filesystem entries.
Project Index
[Project Index]|root:.
|source:git-tracked-files-only
|excluded:{git-ignored,git-untracked}
|.:{.cargo/,.githooks/,.github/,crates/,docs/,scripts/,tests/,xtask/,.editorconfig,.gitignore,.pre-commit-config.yaml,AGENTS.md,Cargo.lock,Cargo.toml,README.md,clippy.toml,deny.toml,rust-toolchain.toml,rustfmt.toml,taplo.toml,typos.toml}
|.cargo:{config.toml}
|.githooks:{pre-merge-commit,prepare-commit-msg}
|.github:{workflows/}
|.github/workflows:{ci.yml}
|crates:{data_store/,meta_control/,node_runtime/,recsql_client/,recsql_core/,recsql_protocol/,recsql_server/,replication/,sql_executor/,sql_frontend/,sql_gateway/,sql_temp/,storage_engine/}
|crates/data_store:{src/,tests/,Cargo.toml,README.md}
|crates/data_store/src:{store/,lib.rs}
|crates/data_store/src/store:{codec/,types/,codec.rs,jobs.rs,lifecycle.rs,lifecycle_command.rs,lifecycle_persistence.rs,lifecycle_snapshot.rs,mod.rs,read.rs,replication_owner.rs,types.rs,write.rs}
|crates/data_store/src/store/codec:{errors.rs,keys.rs,snapshot_log.rs,state.rs,values.rs}
|crates/data_store/src/store/types:{plans.rs}
|crates/data_store/tests:{data_store_contract/,data_store_contract.rs}
|crates/data_store/tests/data_store_contract:{support/,background_owner.rs,moves.rs,mvcc.rs,read_basics.rs,recovery.rs,secondary.rs,support.rs,writes.rs}
|crates/data_store/tests/data_store_contract/support:{catalog.rs,fs.rs,rpc.rs}
|crates/meta_control:{src/,tests/,Cargo.toml,README.md}
|crates/meta_control/src:{control/,lib.rs}
|crates/meta_control/src/control:{admin/,codec/,admin.rs,api.rs,background.rs,catalog.rs,codec.rs,ddl.rs,errors.rs,ids.rs,lifecycle.rs,mod.rs,open.rs,open_config.rs,open_records.rs,open_store.rs,owner.rs,routes.rs,runtime.rs,service.rs,storage.rs,transaction.rs}
|crates/meta_control/src/control/admin:{jobs.rs}
|crates/meta_control/src/control/codec:{catalog_records.rs,job_records.rs,log_snapshot.rs}
|crates/meta_control/tests:{meta_control_contract/,meta_control_contract.rs}
|crates/meta_control/tests/meta_control_contract:{support/,background_jobs.rs,bootstrap_open.rs,errors_jobs.rs,service_admin.rs,support.rs,txn_commit.rs}
|crates/meta_control/tests/meta_control_contract/support:{ddl_helpers.rs,env.rs,fs.rs,rpc.rs}
|crates/node_runtime:{src/,tests/,Cargo.toml,README.md}
|crates/node_runtime/src:{runtime/,lib.rs,test_support.rs}
|crates/node_runtime/src/runtime:{listener/,process/,storage/,config.rs,env.rs,error.rs,json_validation.rs,listener.rs,log.rs,manifest.rs,process.rs,role.rs,rpc.rs,storage.rs,worker.rs}
|crates/node_runtime/src/runtime/listener:{connection/,connection.rs,delivery.rs,finalization.rs,framing.rs,immediate.rs,thread.rs,write.rs}
|crates/node_runtime/src/runtime/listener/connection:{submit.rs,tests.rs}
|crates/node_runtime/src/runtime/process:{handle.rs,startup.rs}
|crates/node_runtime/src/runtime/storage:{file_io.rs,fs_root.rs}
|crates/node_runtime/tests:{node_runtime_contract/,node_runtime_listener_contract/,node_runtime_process_contract/,node_runtime_contract.rs,node_runtime_listener_contract.rs,node_runtime_process_contract.rs}
|crates/node_runtime/tests/node_runtime_contract:{design_state_machine_models/,config.rs,design_internal_state_machine_models.rs,design_state_machine_models.rs,support.rs,utilities.rs}
|crates/node_runtime/tests/node_runtime_contract/design_state_machine_models:{connection.rs,listener.rs,process.rs,request.rs,rpc.rs,sequences.rs}
|crates/node_runtime/tests/node_runtime_listener_contract:{in_flight.rs,protocol.rs,readiness.rs,services.rs,support.rs}
|crates/node_runtime/tests/node_runtime_process_contract:{lifecycle.rs,support.rs}
|crates/recsql_client:{src/,Cargo.toml,README.md}
|crates/recsql_client/src:{lib.rs,main.rs}
|crates/recsql_core:{src/,tests/,Cargo.toml,README.md}
|crates/recsql_core/src:{address.rs,digest.rs,error.rs,fs.rs,ids.rs,lib.rs,limits.rs,log.rs,namespace.rs,numeric.rs,sql.rs,temporal.rs,validation.rs}
|crates/recsql_core/tests:{core_contract.rs}
|crates/recsql_protocol:{src/,tests/,Cargo.toml,README.md}
|crates/recsql_protocol/src:{json_codec/,payload/,error.rs,frame.rs,lib.rs,payload.rs,rpc.rs,service.rs,value.rs}
|crates/recsql_protocol/src/json_codec:{catalog/,rpc_response/,admin.rs,catalog.rs,common.rs,data.rs,mod.rs,response.rs,rpc_request.rs,rpc_response.rs}
|crates/recsql_protocol/src/json_codec/catalog:{cluster.rs,jobs.rs,routes.rs,schema.rs,secondary.rs}
|crates/recsql_protocol/src/json_codec/rpc_response:{body.rs,fields.rs,jobs.rs,validation.rs}
|crates/recsql_protocol/src/payload:{catalog.rs,data.rs,jobs.rs,plans.rs,replication.rs,routing.rs,transactions.rs,write_batch.rs}
|crates/recsql_protocol/tests:{protocol_contract/,protocol_contract.rs}
|crates/recsql_protocol/tests/protocol_contract:{codec.rs,payloads.rs,rpc_registry.rs,rpc_shapes.rs,service_boundary.rs,support.rs}
|crates/recsql_server:{src/,tests/,Cargo.toml,README.md}
|crates/recsql_server/src:{lib.rs,lifecycle.rs,main.rs,open_services.rs,tests.rs}
|crates/recsql_server/tests:{service_slot_contract/,lifecycle_contract.rs,process_entry_contract.rs,role_factory_contract.rs,service_slot_contract.rs}
|crates/recsql_server/tests/service_slot_contract:{dml.rs,read.rs,service_lifecycle.rs,support.rs}
|crates/replication:{src/,tests/,Cargo.toml,README.md}
|crates/replication/src:{state/,error.rs,lib.rs,owner.rs}
|crates/replication/src/state:{delivery.rs,follower.rs,leader.rs,locks.rs,mod.rs,service.rs,storage.rs,util.rs}
|crates/replication/tests:{replication_contract/,replication_contract.rs}
|crates/replication/tests/replication_contract:{support/,follower.rs,leader.rs,opening.rs,snapshot.rs,support.rs}
|crates/replication/tests/replication_contract/support:{env.rs,local_fs.rs,owners.rs,rpc.rs}
|crates/sql_executor:{src/,tests/,Cargo.toml,README.md}
|crates/sql_executor/src:{execute/,write/,config.rs,error.rs,expression.rs,lib.rs,result.rs,rpc.rs,write.rs}
|crates/sql_executor/src/execute:{api.rs,bloom.rs,mod.rs,routes.rs,row_helpers.rs,select.rs}
|crates/sql_executor/src/write:{execute.rs,helpers.rs}
|crates/sql_executor/tests:{sql_executor_contract/,sql_executor_contract.rs}
|crates/sql_executor/tests/sql_executor_contract:{select_contract/,support/,write_contract/,control_resource_contract.rs,coverage_matrix.md,expression_contract.rs,schedule_contract.rs,select_contract.rs,support.rs,write_contract.rs}
|crates/sql_executor/tests/sql_executor_contract/select_contract:{derived_aggregate/,secondary_index/,approximate.rs,derived_aggregate.rs,exists.rs,routing.rs,secondary_index.rs}
|crates/sql_executor/tests/sql_executor_contract/select_contract/derived_aggregate:{min_max.rs}
|crates/sql_executor/tests/sql_executor_contract/select_contract/secondary_index:{index_selection.rs}
|crates/sql_executor/tests/sql_executor_contract/support:{catalog.rs,executor.rs,local_temp.rs,route_helpers.rs,rpc.rs}
|crates/sql_executor/tests/sql_executor_contract/write_contract:{matched_rows.rs,participant_failures.rs,prepare_apply.rs}
|crates/sql_frontend:{src/,tests/,Cargo.toml,README.md}
|crates/sql_frontend/src:{binder/,parser/,plan/,ast.rs,diagnostic.rs,lexer.rs,lib.rs,plan.rs}
|crates/sql_frontend/src/binder:{catalog.rs,context.rs,dml.rs,entry.rs,inference.rs,inference_dml.rs,limits.rs,mod.rs,references.rs,schema.rs,select.rs,select_functions.rs,select_order.rs,select_predicate.rs,select_predicate_approx.rs,select_predicate_exists.rs,select_resolve.rs,validation.rs}
|crates/sql_frontend/src/parser:{ddl.rs,dml.rs,mod.rs,predicate.rs,select.rs,shape.rs,show.rs,tokens.rs}
|crates/sql_frontend/src/plan:{ddl_dml.rs,expression_misc.rs,query.rs}
|crates/sql_frontend/tests:{frontend_contract/,frontend_contract.rs}
|crates/sql_frontend/tests/frontend_contract:{ddl_catalog_schedule.rs,derived_dml.rs,exists_resolution.rs,public_api.rs,select_expressions.rs,support.rs}
|crates/sql_gateway:{src/,tests/,Cargo.toml,README.md}
|crates/sql_gateway/src:{cancellation.rs,execution.rs,execution_ddl_show.rs,execution_read.rs,execution_registered.rs,execution_rpc.rs,execution_write.rs,gateway_errors.rs,gateway_metadata.rs,gateway_rowsets.rs,lib.rs,lifecycle.rs,response.rs,service.rs}
|crates/sql_gateway/tests:{common/,api_config_contract.rs,concurrency_property_contract.rs,integration_style_contract.rs,read_show_contract.rs,registry_cancel_contract.rs,response_assembly_contract.rs,service_validation_contract.rs,write_outcome_contract.rs}
|crates/sql_gateway/tests/common:{fixtures.rs,gateway_helpers.rs,mod.rs,rpc.rs,temp_fs.rs}
|crates/sql_temp:{src/,tests/,Cargo.toml,README.md}
|crates/sql_temp/src:{error.rs,lib.rs,manifest.rs,root.rs,session.rs,types.rs}
|crates/sql_temp/tests:{sql_temp_contract.rs}
|crates/storage_engine:{src/,tests/,Cargo.toml,README.md}
|crates/storage_engine/src:{error.rs,lib.rs,open.rs,record.rs,store.rs,types.rs}
|crates/storage_engine/tests:{storage_contract/,storage_contract.rs}
|crates/storage_engine/tests/storage_contract:{basic.rs,failure.rs,open_cleanup.rs,support.rs}
|docs:{design/}
|docs/design:{00_project_scaffold.md,01_recsql_core.md,02_recsql_protocol.md,03_storage_engine.md,04_sql_temp.md,05_replication.md,06_sql_frontend.md,07_node_runtime.md,08_sql_executor.md,09_meta_control.md,10_data_store.md,11_sql_gateway.md,12_recsql_server.md,99_e2e_tests.md,recsql_system_design.md}
|scripts:{recsql-demo-local.sh}
|tests:{e2e/}
|tests/e2e:{src/,tests/,Cargo.toml,README.md}
|tests/e2e/src:{lib.rs}
|tests/e2e/tests:{support/,sql_statements.rs,topology_admin.rs}
|tests/e2e/tests/support:{mod.rs}
|xtask:{src/,Cargo.toml,README.md}
|xtask/src:{agents_index.rs,lib.rs,main.rs}