Expand description
Valence core ports: storage routing, host-injectable traits, and runtime builder.
§Stack position
valence public crate → valence-core (this crate) → valence-telemetry
backends (mem, surreal, third-party) implement [`DatabaseBackend`]§Entry points
Valence/ValenceBuilder— boot and wire backendsDatabaseBackend— storage adapter trait (openengine_id)DatabaseRouter— heterogeneous engine registryports— secrets, actor, endpoints (host-injectable)Model— generated CRUD surfacettl— schema TTL policy,prepare_create_content, ensure viaValence::ensure_ttl_for_all/Valence::ensure_ttl_for_tablestorage_layout— schema → physical fields; DDL export; ensure/sync typed tables viaValence::ensure_typed_tables_from_registry/Valence::sync_typed_tables_from_registry
§Examples
use std::sync::Arc;
use valence_backend_mem::InMemoryBackend;
use valence_core::Valence;
let valence = Valence::builder()
.add_backend("default", Arc::new(InMemoryBackend::new()))
.build()
.expect("build");
assert!(valence.active_backend().is_ok());§Gotchas
- Engine SDKs and product host crates must never appear in this crate
(use
valence-backend-*and separate host adapters) - Host-owned codegen lives in
valence-codegen, not here - Table TTL is create-only; Deferred backends need the platform sweeper (Future)
Re-exports§
pub use actor::Actor;pub use actor_policy::is_system_shaped_actor;pub use actor_policy::ActorJsonPolicy;pub use actor_policy::ActorTrust;pub use actor_policy::RejectExternalSystemActor;pub use admin_entity_delete::queue_delete_entity;pub use admin_entity_delete::queue_delete_entity_returning_run_id;pub use backend::SqlQueryCompiler;pub use backend::BackendCapabilities;pub use backend::DatabaseBackend;pub use batch::BatchCreatable;pub use compiled_query::CompiledQuery;pub use connection::extract_id_from_record;pub use connection::extract_id_from_record_display;pub use connection::extract_id_from_select_value;pub use connection::id_from_model;pub use connection::Cardinality;pub use connection::IdHolder;pub use connection::OnDelete;pub use currency::Currency;pub use currency::CurrencyCode;pub use currency::CurrencyError;pub use currency::ParseCurrencyCodeError;pub use database_retry::retry_on_database_tx_conflict;pub use deletion::apply_deletion_node;pub use deletion::check_dag_delete_privacy;pub use deletion::check_dag_delete_privacy_with_registry;pub use deletion::dispatch;pub use deletion::is_deletion_dispatcher_registered;pub use deletion::register_deletion_dispatcher;pub use deletion::register_noop_deletion_dispatcher_for_tests;pub use deletion::DeletionRequest;pub use deletion::DeletionService;pub use entity::ValenceEntity;pub use error::Error;pub use error::Result;pub use evaluator::Database;pub use evaluator::DatabaseEvaluator;pub use evaluator::DatabaseFromEngine;pub use evaluator::ResolverContext;pub use evaluator::DEFAULT_IN_MEMORY;pub use evaluator::DEFAULT_IN_MEMORY_ROUTER_KEY;pub use iter::find_iter_descriptor;pub use iter::iter_descriptors_for_table;pub use iter::IterDescriptor;pub use iter::IterEvaluation;pub use iter::IterExecuteFn;pub use iter::IterShouldRunFn;pub use known_engines::KnownEngines;pub use model::FieldOperation;pub use model::Model;pub use model::PrivacyError;pub use model::SchemaMetadata;pub use owner_ref::OwnerKind;pub use owner_ref::OwnerRef;pub use owner_ref::OwnershipConfig;pub use ownership::OwnershipService;pub use ports::actor::ActorContext;pub use ports::actor::ActorFactory;pub use ports::actor::JsonActorContext;pub use ports::actor::JsonActorFactory;pub use ports::endpoints::DatabaseEndpointResolver;pub use ports::endpoints::EnvEndpointResolver;pub use ports::endpoints::NoopEndpointResolver;pub use ports::endpoints::StaticEndpointResolver;pub use ports::secrets::EnvSecretProvider;pub use ports::secrets::NoOpSecretProvider;pub use ports::secrets::SecretProvider;pub use privacy::privacy_bypass_active;pub use privacy::PolicyEvaluator;pub use privacy::PrivacyEvaluator;pub use privacy::PrivacyOperation;pub use privacy::PrivacyRule;pub use privacy::PRIVACY_BYPASS_ENV;pub use privacy::PRIVACY_BYPASS_FORCE_ON_ENV;pub use query::DateTimePredicate;pub use query::HopSource;pub use query::HopType;pub use query::IdOnlyRecord;pub use query::IntPredicate;pub use query::NullPredicate;pub use query::QueryCore;pub use query::RecordPredicate;pub use query::SortDirection;pub use query::StringPredicate;pub use query::MAX_QUERY_LIMIT;pub use query::MAX_QUERY_OFFSET;pub use query_compiler::QueryCompiler;pub use query_compiler_registry::compile_for_engine;pub use query_compiler_registry::global_compiler_registry;pub use query_compiler_registry::QueryCompilerRegistry;pub use read_cache::get_record_via_cache;pub use read_cache::get_record_with_ownership_bundle_via_cache;pub use read_cache::invalidate;pub use read_cache::invalidate_for_backend;pub use read_cache::read_cache_enabled;pub use record_id::RecordId;pub use redact::redact_credentials_in_text;pub use redact::redact_endpoint;pub use reference::Reference;pub use reference::ReferencedEntity;pub use reference::WithReference;pub use register_logical::register_backend_logical_names;pub use register_logical::register_backend_logical_names_slices;pub use register_logical::RegisterBackendLogicalNamesOptions;pub use request_cache::RequestPermissionCache;pub use router::DatabaseRouter;pub use router_key::router_key;pub use runtime::RouterValenceFactory;pub use runtime::RouterValenceFactoryConfig;pub use runtime::Valence;pub use runtime::ValenceBuilder;pub use runtime::ValenceFactory;pub use schema::schema_connections_for_table;pub use schema::SchemaConnectionsOverlayInit;pub use schema::SchemaMetadataInit;pub use schema::SchemaMetadataStruct;pub use schema::SchemaRegistry;pub use schema_api::ForeignKeyRef;pub use schema_api::Schema;pub use schema_api::SchemaConnection;pub use schema_api::SchemaEdge;pub use schema_api::SchemaField;pub use schema_api::SchemaMeta;pub use schema_api::SchemaPolicies;pub use schema_api::SchemaPolicyRule;pub use schema_api::SchemaPolicyRules;pub use schema_api::SchemaPrivacy;pub use schema_types::FieldType;pub use schema_types::JsonAsSerdeError;pub use schema_types::Role;pub use schema_types::Validator;pub use side_effect::FieldChange;pub use side_effect::Mutation;pub use side_effect::MutationKind;pub use side_effect::SideEffect;pub use storage_layout::AdditiveOp;pub use storage_layout::FieldStorage;pub use storage_layout::LayoutDiff;pub use storage_layout::LayoutField;pub use storage_layout::SqlColumnType;pub use storage_layout::StorageLayout;pub use storage_layout::SurrealFieldType;pub use trait_registry::TraitRegistry;pub use trait_schema::TraitDefinition;pub use trait_schema::TraitDefinitionInit;pub use trait_schema::TraitFieldDef;pub use trait_schema::TraitImplementor;pub use trait_schema::TraitPolicies;pub use trait_schema::TraitPolicyRules;pub use ttl::list_ttl_table_names;pub use ttl::prepare_create_content;pub use ttl::BackendTtlCapability;pub use ttl::SchemaTtlPolicy;pub use ttl::EXPIRE_AT_FIELD;pub use instrumentation::wrap_backend;pub use instrumentation::InstrumentedBackend;pub use instrumentation::MutationTimer;pub use inventory;
Modules§
- actor
- Actor identity for privacy checks and audit trails.
- actor_
policy - Optional policy for validating opaque
actor_jsonat factory build time. - admin_
entity_ delete - Table-keyed queued delete for admin tooling.
- backend
- Pluggable database backends for Valence.
- batch
- Batch create hooks for codegen
BatchCreatableimpls (full batch runtime is host-owned). - compiled_
query - Parameterized statement for
crate::backend::DatabaseBackend::execute_compiled_query. - compiled_
query_ factory - Dialect-specific compiled queries for deletion DAG and ownership helpers.
- connection
- Connection cardinality, delete semantics, and id helpers for generated models.
- currency
- Monetary amount with an ISO-4217
CurrencyCode. - database_
retry - Retry database operations when the engine reports retryable transaction contention.
- datetime_
unix - Persist
chrono::DateTime<Utc>as signed UTC unix seconds. - deletion
- Cascading delete orchestration — dispatch hooks and DAG planning.
- entity
- Privacy-filtered entity view for admin tooling.
- error
- Error types for Valence routing and backends.
- evaluator
- Runtime resolution of which
crate::backend::DatabaseBackenda schema uses. - instrumentation
- Instrumentation hooks for Valence runtime metrics and events.
- iter
- Row-level iter descriptor types for
valence_schema! { iters: [...] }. - json_as
- Serde helpers for
FieldType::JsonAsfields. - known_
engines - Stable engine id slugs for first-party reference adapters.
- model
- Model contracts generated from schema DSL.
- owner_
ref - Stable owner identity for row-level ownership metadata.
- ownership
- First-class data ownership (platform tables + hooks from generated CRUD).
- ports
- Host-injectable ports (secrets, identity, endpoints).
- privacy
- Schema-driven privacy for entity and field access.
- privacy_
policies - Re-export built-in privacy policy constants for schema authors.
- query
- Composable query builder — filters, sorts, compiled execution.
- query_
compiler - Query compilation from
crate::query::QueryCoretocrate::compiled_query::CompiledQuery. - query_
compiler_ registry - Registry mapping
DatabaseBackend::engine_idto query compilers. - read_
cache - Valence-wide read-through LRU for
Model::get-shaped point reads. - record_
id - Backend-agnostic record identifier (
table+id). - redact
- Redact credentials from connection endpoints and error text.
- reference
- Reference placeholders for batch entity creation.
- register_
logical - Multi-logical registration of a shared
DatabaseBackendon aDatabaseRouter. - registry
- Generic string-keyed registry (inventory + HashMap, no quark dependency).
- request_
cache - Request-scoped permission check cache (shared via
Arcon clonedValencehandles). - router
- Named backend registry (heterogeneous engines per router).
- router_
key - Compound router keys:
"{engine_id}:{logical_name}". - row_
json - JSON row helpers shared by query fetch paths.
- runtime
- Valence runtime handle and builder.
- safe_
ident - Charset validation for SQL/Surreal identifiers interpolated into queries.
- schema
- Schema metadata registration hooks for
valence_schema!. - schema_
api - Structured schema metadata produced by the Valence DSL.
- schema_
types - DSL type vocabulary used by
valence_schema!andvalence_trait_schema!. - side_
effect - Side effect types for post-mutation hooks.
- storage_
layout - Schema-driven physical storage layout and dialect DDL export.
- trait_
registry - Runtime trait metadata registry.
- trait_
schema - Trait schema metadata for
valence_trait_schema!. - ttl
- Table-level TTL: schema policy, create-time stamping, and ensure APIs.
- validation
- Field validation framework
Structs§
- Console
Sink - Writes telemetry to stderr (development and bench).
- NoOp
Sink - Discards all telemetry (default for tests and minimal hosts).
Traits§
- Telemetry
Sink - Host-injectable telemetry sink for Valence ORM metrics and events.