Rust SDK Reference (`schemabound`)

The schemabound crate is the core Rust runtime and reference implementation of the OAM framework. All other SDKs and services build on this foundation.

Crate Structure

Module	Purpose
`schemabound::mirror`	SQLite schema introspection — tables, columns, indexes, triggers, UDTs, field mappings
`schemabound::executor`	`SchemaService` / `QueryService` traits + SQLite implementations
`schemabound::grpc_executor`	Tonic gRPC server wrapping the executor services
`schemabound::interceptor`	Typed event bus — `Event` enum, `EventBus`, `EventHandler`, `HandleOutcome`
`schemabound::handlers`	Built-in CoR handlers — `AuditLogHandler`, `QueryMetricsHandler`, `SessionActivityHandler`, `DefaultHandlerChain`, `SharedHandler`
`schemabound::tcp`	TCP JSON-RPC transport and per-client auth
`schemabound::policy_engine`	Tool-contract policy evaluation and subquery governance
`schemabound::runtime_context`	`QueryRuntimeContext` — the carrier for per-request augmentation metadata
`schemabound::rate_limit`	Connection and request rate limiter
`schemabound::mapper`	`Mapper` trait + `LocalMapper` (SQLite) + `TcpMapper` (remote)

Schema Introspection Model

The mirror module returns a tree of Rust structs:

SchemaModel
├── tables: Vec<Table>
│   ├── columns: Vec<Column>          name, sql_type, nullable, primary_key, default_value
│   ├── indexes: Vec<Index>           name, columns
│   ├── unique_indexes: Vec<UniqueIndex>
│   ├── foreign_keys: Vec<ForeignKey>
│   ├── composite_foreign_keys: Vec<CompositeForeignKey>
│   ├── triggers: Vec<Trigger>        name, event, timing, table_name, body
│   └── field_mappings: Vec<FieldMapping>
│       └── logical_name, physical_name, orm_convention  (Hibernate | EntityFramework)
└── user_defined_types: Vec<UserDefinedType>
    └── name, base_type, check_constraint, nullable, default_value

Field mapping convention detection is heuristic:

camelCase column names → Hibernate
PascalCase column names → EntityFramework (Entity Framework)
_prefixed columns → EntityFramework (EF Core shadow property convention)

gRPC Proto Mapping

The table_to_table_def function converts a mirror::Table to a proto TableDef:

#![allow(unused)]
fn main() {
use schemabound::grpc_executor::table_to_table_def;

let proto_table = table_to_table_def(&my_mirror_table);
}

Both unique_indexes and indexes are merged into TableDef.indexes, distinguished by IndexDef.is_unique.

Contributing

See the Contribution Workflow for the full TDD contract — no production code may be written before a failing test exists.

Test Targets

# Unit tests only (fast, no infra)
make test-unit

# Full test suite (schemabound-public)
make test FILTER=schemabound-public

# Proto unit tests
make test-proto

Keyboard shortcuts