SCHEMABOUND Documentation — Choose Your Path

Different roles need different entry points into this documentation. Select the persona that matches your responsibilities to jump directly to relevant material, or use the full table of contents below for complete coverage.

For Product Managers & Executives

Focus on business outcomes, cost governance models, and strategic adoption decisions. You don’t need to understand implementation details — you need to know what SCHEMABOUND does and why it matters.

• The Object Agent Mapping Paradigm — How OAM differs from traditional ORMs by mapping agent intent to data operations rather than simply mapping objects to relational rows
• System Architecture Overview — High-level view of where SCHEMABOUND sits between your application and your data layer
• AAU Billing Reference — Cost governance model: how Agentic Activity Units quantify governance cost per tool call (Read = 1x, Write = 3x, Governed = 5x)
• Demo — Executive narrated demo showing SCHEMABOUND in action

Key takeaway: SCHEMABOUND reduces governance costs by providing fine-grained audit trails and policy enforcement without requiring you to rewrite existing code. The Hybrid operating mode lets you integrate legacy databases incrementally while Code-First schemas give you full control over new development.

For Backend & DevSecOps Engineers

Focus on operational configuration, security hardening, deployment procedures, and audit trail verification. You need exact environment variables, dependency ordering, and production-ready patterns.

• Identity & Security Operations — mTLS setup, LDAP sync, JWT rotation, RBAC mapping, SCIM provisioning, session management, host hardening
• Runtime Operations — Audit logging configuration, self-healing infrastructure workers, event publishing pipeline
• Air-Gap Deployment — Production deployment in disconnected environments with hardware provisioning and remote attestation
• C4 Model Diagrams — Visual models showing how SCHEMABOUND gRPC Server, EventBus, Auto-Rewind workers, and Chain Integrity verification interact

Key takeaway: Every agent action is captured in a tamper-evident SHA-256 hash chain exported via MultiTransportExporter to SIEM platforms. Configure mTLS with schemabound-certgen, rotate JWT secrets without downtime using SCHEMABOUND_JWT_SECRETS, and rely on the self-healing infrastructure workers to maintain deployment integrity automatically.

For Application Developers

Focus on SDK integration, rapid prototyping, component usage, and API reference. You need working code examples, dependency installation commands, and clear method signatures.

• Tutorials — Rust, Python, .NET, TypeScript quick starts for spinning up your first SCHEMABOUND client
• How-To Guides — Inject runtime context headers, execute multi-step control plane workflows, manage declarative migrations with sb-migrate
• API Reference — Generated SDK documentation for all supported languages and protocols

Key takeaway: Install your language-specific SDK (schemabound, schemabound-python, Schemabound.Dotnet, or the TypeScript package), connect to the backend, and start writing queries. The LlmSchema derive macro generates JSON schemas automatically from your Rust structs; use ValidateQueryRequest for validation and ExecuteStepRequest for multi-step workflows.

Full Table of Contents

If you’re exploring SCHEMABOUND broadly or need coverage across all personas, use the complete navigation:

• Part 1: Concepts (Why) — Explanation for product managers, architects, and developers seeking to understand the “Why” before writing code
• Part 2: Tutorials (Learn by Doing) — Quick Start guides providing step-by-step onboarding experiences
• Part 3: How-To Guides (Solve a Problem) — Goal-oriented operational guides for competent engineers actively building systems
• Part 4: Identity & Security Operations (Hybrid) — Mixed explanation and how-to content for identity and security configuration
• Part 5: Runtime Operations (Hybrid) — Mixed explanation and how-to content for DevOps/SRE engineers running the system in production
• Part 6: Deployment & Infrastructure (How-To) — Operational guides for deploying SCHEMABOUND in production and air-gap environments
• Part 7: Technical Reference (Look Up Facts) — Narrative-free data dictionaries, API contracts, and trait definitions
• Glossary — Centralized terminology for domain-specific concepts
• Contributing — Contribution workflow, testing, and release procedures

Demo

Family Tree — AI-Narrated Demo (Developer)

The same end-to-end recording narrated for a software developer evaluating the SCHEMABOUND SDK. Highlights SchemaboundDeclarativeBase, _call_gemini + gRPC agent memory, and TestClient for unit testing.

Regenerate: GEMINI_API_KEY=<key> make narrate DEMO=family-tree PERSONA=developer from the repository root.

Family Tree — AI-Narrated Demo (Executive)

The same recording narrated for a business executive evaluating SCHEMABOUND. Focuses on cost avoidance, always-current documentation, and SCHEMABOUND’s Data-First / Code-First / Hybrid operating modes — no full rewrite required.

Regenerate: GEMINI_API_KEY=<key> make narrate DEMO=family-tree PERSONA=executive from the repository root.

Family Tree — AI-Narrated Demo (DevSecOps)

The same recording narrated for a DevSecOps engineer or security auditor. Covers session tracking, structured audit logging via gRPC, RBAC enforcement at the data layer, and the security observability that SCHEMABOUND Enterprise provides out of the box.

Regenerate: GEMINI_API_KEY=<key> make narrate DEMO=family-tree PERSONA=devsecops from the repository root.

Introduction

OAM — Object Agent Mapping — is the framework for giving agents, services, and automation structured and policy-aware access to data.

Where an ORM (Object Relational Mapping) maps application objects to relational rows, OAM maps agent intent to data operations. The framework controls how an agent discovers, accesses, and works with data — and enforces those rules consistently across languages and deployment patterns.

SCHEMABOUND is the runtime that implements OAM. It provides identity-aware execution, policy enforcement, and agent-ready context across application and service boundaries.

Schema Modes

OAM defines three operating modes that determine how an agent interacts with data:

Choose Data-First when agents need to explore data without committing to a code model. Choose Code-First when your application owns the data and must enforce validation rules. Use Hybrid when your codebase covers some tables but you still want introspection for the rest.

What This Book Covers

• Architecture explains how SCHEMABOUND fits into application, service, and event-driven systems.
• Runtime Context explains how request metadata and runtime augmentation travel with execution.
• Contributing explains how to propose changes to the public runtime, SDKs, and documentation.
• SDK Guides help you choose the best starting point for Python and .NET integrations.

Where SCHEMABOUND Fits

SCHEMABOUND is designed for teams that want to:

• add policy-aware execution to application and service workflows
• carry stable identity and organization context through runtime operations
• integrate agent-driven or automation-driven behavior without rewriting existing systems
• standardize public integration contracts across multiple languages
• capture a tamper-evident audit trail of every agent action for SIEM and AI-SPM ingestion
• detect and respond to prompt injection, jailbreak attempts, and adversarial inputs at the gateway

Operating Patterns

SCHEMABOUND typically appears in one of two patterns:

• Application-intercepted flows where SCHEMABOUND validates and enriches requests as they move through an API or service boundary.
• Event-driven flows where SCHEMABOUND observes or participates in runtime decisions driven by messages, RPC calls, or automation pipelines.

Quick Links

• schemabound-public for the public Rust core and shared runtime contract
• schemabound-python for Python integrations and automation workflows
• schemabound-dotnet for .NET services and typed enterprise integrations

Suggested Starting Path

1. Start with Architecture Overview to understand the public runtime model.
2. Read Runtime Context if you need request metadata and runtime-augmentation guidance.
3. Choose your SDK: Python or .NET.
4. Use API Reference when you are ready for package and protocol details.

Architecture Overview

SCHEMABOUND is designed as a public runtime layer that sits close to execution boundaries. It helps products and services carry identity, policy, and agent-aware context through application logic without forcing teams to redesign the rest of their stack.

The Object Agent Mapping Model

OAM gives the architecture a stable contract for how agents interact with data. Instead of giving an agent direct or unrestricted database access, OAM sits between the agent and the data layer and mediates what the agent can see and do based on the active schema mode.

Schema mode is selected at agent registration time and governs the entire session:

• In Data-First mode, the runtime introspects the live database so the agent can discover and query data without a pre-defined application model. Access is read-only.
• In Code-First mode, only explicitly registered application models are accessible. The application controls validation and data access rules, enabling safe read-write operations.
• In Hybrid mode, registered models take precedence for known tables and the runtime falls back to introspection for everything else. Access is read-only where code coverage ends.

All three modes carry identity and runtime context through the execution path so agent queries stay aligned with organizational policy regardless of which mode is active.

Public Runtime At A Glance

The public SCHEMABOUND surface is organized around three adoption layers:

1. Core runtime for shared execution, reflection, and protocol behavior.
2. Language SDKs for integrating SCHEMABOUND into Python and .NET applications.
3. Shared protocol definitions for teams that need language-neutral contracts or generated bindings.

Public Building Blocks

Runtime Model

The runtime model gives SCHEMABOUND a consistent way to:

• interpret structured requests and tool-facing operations
• apply identity and organization context to execution
• attach runtime augmentation metadata before validation and execution
• emit audit-safe events and observable outcomes

The runtime exposes typed error enums — not boxed trait objects — at every public boundary. Each operation returns a specific error type (MapperError, ExecutorError, EngineError, ControlPlaneError, and others) that maps cleanly to gRPC status codes and propagates with ? in Rust call sites. See the Rust SDK error handling reference for the full type registry.

SDK Layer

The Python and .NET SDKs package that runtime model into language-specific integration surfaces. They are the fastest path for teams that want to add SCHEMABOUND to existing products, services, and automation workflows.

Shared Contract

When teams need multi-language interoperability, generated clients, or direct protocol-level integration, the shared protobuf and gRPC contract provides the stable public boundary.

Where SCHEMABOUND Fits In The Stack

SCHEMABOUND usually appears in one of these roles:

• Request-path integration where a service or API validates and enriches execution context before work continues.
• Runtime coordination where a client or middleware layer passes identity, tool, and organization context into downstream execution.
• Event-driven integration where SCHEMABOUND participates in decisions triggered by messages, jobs, or automation pipelines.

Adoption Paths

Start With An SDK

Use an SDK when you want to move quickly inside an application stack. This is the best fit for:

• service teams integrating SCHEMABOUND into existing APIs
• platform teams standardizing runtime context across applications
• automation teams building product or operations workflows

Start With The Shared Contract

Use the protocol definitions when you want to:

• generate your own client bindings
• align multiple services around one public contract
• integrate from a language or platform that does not yet have a first-party SDK

Operating Modes

SCHEMABOUND supports both user-driven and event-driven execution patterns.

Application-Driven Mode

In application-driven flows, a user or upstream service initiates the request. SCHEMABOUND enriches or validates that request as it moves through an application or API boundary.

Event-Driven Mode

In event-driven flows, SCHEMABOUND participates when a message, RPC call, or background job creates a decision point that needs shared runtime context or policy-aware behavior.

Agent Memory

Agent Memory gives SCHEMABOUND sessions an isolated, auditable memory store. Each session accumulates its own history of observations, tool calls, and decisions — scoped so that one session never reads or contaminates another, and past context can always be retrieved exactly as it was recorded.

What it provides:

• Per-session isolation — memory written during one session is never visible to another
• Chronological history — entries are ordered and retrievable in the sequence they were recorded
• Reproducibility — prior agent observations, tool call results, and decisions remain accessible across the full lifetime of a session
• Prompt augmentation — session memory can be injected automatically into prompt hooks so agents carry prior context without the caller managing it manually

See Prompt Augmentation Guide for operational details on injecting {{memory_context}} into your workflows.

System Architecture — C4 Model

Visual models organized by zoom level, following the C4 model (Context → Containers → Components → Code). Each level targets a different stakeholder persona and abstracts away implementation details progressively as you zoom in.

Level 1: Context (Business Stakeholders & Product Managers)

Shows how SCHEMABOUND fits into your broader ecosystem — external systems, identity providers, and data layers. This is the “elevator pitch” architecture diagram that explains what SCHEMABOUND connects to without revealing internal implementation.

graph LR
    LLM["LLM<br>Agent"] --> SB["SCHEMABOUND<br>Middleware"]
    SB --> IdP["Identity<br>Provider (BYOI)"]
    SB --> DB["Data<br>Layer"]
    SB --> SIEM["SIEM<br>Platform"]

What it shows at a glance: SCHEMABOUND sits between your LLM Agent and four external systems — identity providers (BYOI), data stores, audit platforms, and telemetry backends. No internal implementation details are exposed at this level; those appear in the Container diagram below.

Level 2: Container (Frontend/Backend Developers & DevOps)

Illustrates the main boundaries and high-level data flow within SCHEMABOUND itself. This level is relevant when you’re configuring deployment, tuning workers, or integrating with observability platforms.

graph TB
    LLM["LLM<br>Agent"] --> gRPC["gRPC Server<br/>(:50051)"]
    IdP["Identity<br>Provider"] -->|"JWT/OIDC"| gRPC
    DB["Database"] -->|"Query results"| gRPC
    gRPC --> EB["Global<br>EventBus"]
    EB --> W["Data Resilience Workers<br/>Auto-Rewind + Chain Integrity"]

Key boundaries:

• gRPC Server accepts ExecuteStepRequest and SubmitPlanRequest from LLM Agents; validates JWT/OIDC tokens via BYOI identity layer
• Global EventBus is the typed event bus that fans out LlmToolCallAuditRecorded events to all registered handlers (audit log, query metrics, session activity)
• Data Resilience Workers run in background: Auto-Rewind handles schema topology refresh and historical replay; Chain Integrity verifies hash-chain anchor depths

Level 3: Component (Backend Engineers)

Maps internal structures and responsibilities within the SCHEMABOUND runtime. This level is relevant when you’re implementing custom handlers, extending the injection guard, or debugging query execution paths.

graph LR
    IG["Injection<br>Guard"] --> LM["LocalMapper<br>(SQLite)"]
    RC["Runtime Context"] --> TC["Tool Contract Policy Engine"]
    TC -->|"Intent: read/write/admin"| LM
    TC --> TM["TcpMapper<br>(Remote TCP/JSON-RPC)"]
    LM -->|QueryExecuted| AL["AuditLogHandler<br>(OCSF v1.1)"]
    TM -->|QueryExecuted| QM["QueryMetricsHandler<br>(AAU tracking)"]
    TC --> SA["SessionActivityHandler<br>(per-session memory)"]

Component responsibilities:

• Injection Guard filters traffic against regex pattern libraries (jailbreak_token, sql_template_injection) before the request reaches mappers; policy controlled by SCHEMABOUND_INJECTION_POLICY (observe vs. block)
• LocalMapper/ TcpMapper execute queries via SQLite or remote TCP transport with configurable timeouts (DEFAULT_TIMEOUT_SECONDS = 30s)
• Tool Contract Policy Engine classifies intent (Read=1x, Write=3x, Governed=5x AAU weight) and enforces governance rules per tool call
• Chain of Responsibility handlers receive QueryExecuted events: AuditLogHandler produces OCSF v1.1 records, QueryMetricsHandler tracks AAU totals, SessionActivityHandler captures per-session memory entries

Level 4: Code (Core Contributors)

Reserved for core contributors seeking exact implementation details — class hierarchies, trait implementations, and payload structures inside the sb-migrate compilation path. This level uses UML-style diagrams to show how domain objects transform into migration plan steps.

classDiagram
    TableSnapshot --> MigrationPlan : diff_snapshots()
    MigrationPlan *-- MigrationStep : contains
    MigrationParser --> MigrationPlan : parses
    
    class TableSnapshot {
        +columns: Vec<ColumnDef>
        +indexes: Vec<IndexDef>
        +diff_against(other) MigrationPlan
    }
    
    class MigrationPlan {
        +id: String
        +direction: MigrationDirection
        +steps: Vec<MigrationStep>
        +serialize() JSON
    }
    
    class MigrationStep {
        +action: StepAction
        +table_name: String
        +sql_dialect: DatabaseDialect
    }

Key transformations:

• TableSnapshot is produced by the MirrorProvider during schema introspection; contains columns, indexes, unique constraints, and field mappings with ORM convention detection (Hibernate vs EntityFramework)
• diff_snapshots() computes a MigrationPlan containing ordered MigrationStep payloads tagged with DatabaseDialect (PostgreSQL, MySQL, SQLite, Dolt)
• MigrationParser reads JSON from stdin via the sb-migrate binary protocol, validates dependency acyclicity, and emits typed migration steps for execution

Using These Diagrams in Documentation

When referencing SCHEMABOUND architecture in backlog issues or PR descriptions:

• Use Level 1 diagrams when explaining to non-engineers what SCHEMABOUND connects to
• Use Level 2 diagrams when configuring deployment, workers, or observability integration
• Use Level 3 diagrams when implementing custom handlers or debugging query paths
• Use Level 4 diagrams only in core contributor documentation — never expose this level in user-facing docs

Render these diagrams locally with mdbook (Mermaid is configured via mdbook-mermaid preprocessor) or paste into any Mermaid-compatible viewer.

Identity And BYOI

SCHEMABOUND follows a Bring Your Own Identity approach so teams can integrate with the identity systems they already trust instead of recreating users, roles, and organization structure from scratch.

What BYOI Looks Like In Practice

With BYOI, SCHEMABOUND aligns runtime behavior with your existing identity model by mapping external identity information into the public execution context.

That usually means carrying forward:

• organization or tenant boundaries
• user and service identity
• role or permission context
• capability or scope information that affects execution decisions

Why This Matters

Identity-aware execution helps teams:

• keep SCHEMABOUND aligned with existing access-control boundaries
• preserve organizational context across application and service calls
• reduce drift between product identity and runtime behavior
• support agent and automation workflows without inventing a parallel permission system

Common Identity Sources

SCHEMABOUND is well suited to identity models that originate from systems such as:

• enterprise directory providers
• source-control and collaboration platforms
• service-owned role and entitlement systems
• data-layer roles or scope definitions

The exact integration path can vary, but the goal stays the same: keep runtime decisions grounded in the identity model your organization already operates.

Identity In The Execution Path

Identity becomes most useful when it arrives with the request itself. In practice, that means SCHEMABOUND can use identity context to:

• interpret which organization or tenant owns the request
• understand which actor initiated the work
• choose the right runtime augmentation or policy path
• emit more meaningful, audit-safe runtime events

Integration Guidance

The best BYOI integrations keep identity signals stable, explicit, and close to the request boundary.

Start by identifying:

• which system is the source of truth for identity
• which parts of that identity must influence runtime decisions
• which fields need to travel through the public SCHEMABOUND headers or protocol surface

From there, use SCHEMABOUND to preserve that context consistently across clients, services, and execution paths.

Rust Integration Tutorial

This tutorial walks you through adding SCHEMABOUND to a Rust project and spinning up a local gRPC server on port 50051. By the end, you will have a running instance that can introspect SQLite databases and enforce policy on queries.

Installation

Add schemabound to your Cargo.toml:

[dependencies]
schemabound = "0.6"
tokio = { version = "1", features = ["full"] }

Start a gRPC Server

use schemabound::grpc_executor::GrpcExecutor;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let executor = GrpcExecutor::new("path/to/database.db")?;
    let handle = executor.start_server("0.0.0.0:50051").await?;
    handle.await?;
    Ok(())
}

Introspect a SQLite Database

#![allow(unused)]
fn main() {
use schemabound::mirror::introspect_sqlite_path;

let schema = introspect_sqlite_path("path/to/database.db")?;

for table in &schema.tables {
    println!("Table: {}", table.name);
    for col in &table.columns {
        println!("  Column: {} ({}){}", col.name, col.sql_type,
            if col.primary_key { " PK" } else { "" });
    }
    for trigger in &table.triggers {
        println!("  Trigger: {} {} {}", trigger.name, trigger.timing, trigger.event);
    }
}

println!("UDTs: {}", schema.user_defined_types.len());
}

Use The MirrorProvider Trait

MirrorProvider is an async trait for pluggable schema introspection:

#![allow(unused)]
fn main() {
use schemabound::{MirrorProvider, SqliteMirrorProvider};

let provider = SqliteMirrorProvider::new("database.db");
let schema = provider.introspect_schema().await?;
}

Implement the trait to integrate custom databases:

#![allow(unused)]
fn main() {
use schemabound::MirrorProvider;
use schemabound::mirror::SchemaModel;

struct MyCustomProvider;

#[async_trait::async_trait]
impl MirrorProvider for MyCustomProvider {
    async fn introspect_schema(&self) -> Result<SchemaModel, String> {
        // custom introspection logic
        Ok(SchemaModel { tables: vec![], user_defined_types: vec![] })
    }
}
}

Register a CoR Handler

Handlers are invoked in registration order for every dispatched event. Use the built-in collection from schemabound::handlers or implement EventHandler yourself:

#![allow(unused)]
fn main() {
use schemabound::{get_event_bus, AuditLogHandler, DefaultHandlerChain, SharedHandler};
use std::sync::Arc;

let chain = DefaultHandlerChain::new();
let bus = get_event_bus();

bus.register_handler(Box::new(AuditLogHandler))?;
bus.register_handler(Box::new(SharedHandler(Arc::clone(&chain.query_metrics))))?;
bus.register_handler(Box::new(SharedHandler(Arc::clone(&chain.session_activity))))?;

let snap = chain.query_metrics.snapshot();
let sessions = chain.session_activity.session_count();
}

Subscribe to Events (fire-and-forget)

#![allow(unused)]
fn main() {
use schemabound::interceptor::{get_event_bus, Event};

let bus = get_event_bus();

let id = bus.register_subscriber(Box::new(|event: &Event| {
    println!("Event: {}", event.event_type());
}))?;

bus.unregister_subscriber(id)?;
}

Apply a Policy to a Query

#![allow(unused)]
fn main() {
use schemabound::executor::{QueryServiceImpl, ValidateQueryRequest};
use schemabound::policy_engine::{
    AuthorizationContext, AuthorizedSubqueryShape, PolicyContext, SubqueryPolicy, ToolContract, ToolIntent,
};

let mut service = QueryServiceImpl::new();
service.set_db_path("database.db")?;

let request = ValidateQueryRequest {
    db_identifier: "db".into(),
    query: "SELECT id FROM users WHERE org_id IN (SELECT id FROM organizations)".into(),
    parameters: Default::default(),
};

let policy = PolicyContext {
    tool: ToolContract {
        name: "list-users".into(),
        intent: ToolIntent::ReadSelect,
        subquery_policy: SubqueryPolicy::AllowListed(vec![
            AuthorizedSubqueryShape { table: "organizations".into() },
        ]),
    },
    authorization: AuthorizationContext {
        allowed_intents: vec![ToolIntent::ReadSelect],
        grants: vec!["tool:users.read".into()],
    },
};

let response = service.validate_query_with_policy(request, policy).await?;
assert!(response.valid);
}

Next Steps

• Reference: See Rust SDK Reference for crate structure, error handling, and gRPC proto mapping.
• Event Pipeline: See Event Pipeline architecture guide for the full handler reference.
• Contributing: See Contribution Workflow for the TDD contract.

Python Automation Tutorial

This tutorial walks you through installing schemabound-python and executing your first database introspection using the declarative base pattern.

Installation

pip install schemabound-python

Connect to SCHEMABOUND Backend

from schemabound_sdk import SchemaboundClient, SchemaboundDeclarativeBase

# Connect to SCHEMABOUND backend
client = SchemaboundClient(uri="localhost:50051")
client.ping()  # Verify connectivity

# Use as a SQLAlchemy declarative base for schema introspection
class User(SchemaboundDeclarativeBase):
    __tablename__ = "users"

This is the fastest path when you want to stand up a Python-based integration, validate connectivity, and start building application logic around SCHEMABOUND.

Next Steps

• Reference: See Python SDK Reference for full API surface, method signatures, and runtime augmentation headers.
• Contributing: See Contribution Workflow for the TDD contract.

.NET Enterprise Tutorial (stub)

This tutorial will cover:

• Adding Schemabound.DotNet NuGet package to an ASP.NET Core worker service
• Initializing the ReflectionEngine with your domain models
• Using LlmSchema derive macro equivalents in C# for automatic JSON schema generation
• Configuring gRPC client connections to SCHEMABOUND backend services

TypeScript / Node.js Tutorial (stub)

This tutorial will cover:

• Installing the schemabound-ts package
• Using MigrationEngine for declarative DDL revision control in CI/CD pipelines
• Executing schema diffs and applying migration plans via the JSON stdin protocol

Go Tutorial (stub)

This tutorial will cover:

• Generating gRPC client bindings from schemabound-proto using protoc-gen-go-grpc
• Configuring Tonic-compatible transport for SCHEMABOUND services
• Implementing custom MirrorProvider and QueryRuntimeAugmentor traits in Go

Kotlin Tutorial (stub)

This tutorial will cover:

• Using schemabound-emgen for zero-copy binary serialization on Android XR edge hardware
• Generating Kotlin gRPC stubs from shared protobuf contracts
• Integrating SCHEMABOUND into Android XR applications with <50ms round-trip latency

Swift Tutorial (stub)

This tutorial will cover:

• Integrating SCHEMABOUND into iOS/macOS agent applications via gRPC client bindings
• Using the OAM framework for policy-aware data access on Apple platforms
• Implementing custom MirrorProvider for Core Data schema introspection

Runtime Context

Runtime context is how SCHEMABOUND keeps execution grounded in the real application state that surrounds a request. It gives clients and services a public way to attach stable metadata before validation and execution begin.

Why Runtime Context Matters

Runtime context helps SCHEMABOUND answer practical questions such as:

• which tool or product surface initiated this request
• which user or organization the request belongs to
• which domain tags or table scopes matter for this execution
• which runtime augmentation should be applied before downstream work continues

Without that context, a request may still be valid at the protocol level but incomplete from a product and governance perspective.

Runtime Augmentation

Runtime augmentation is the public mechanism for selecting additional execution context before a request is evaluated.

Clients can use:

• x-schemabound-runtime-augmentation-id when they already know the specific augmentation identifier
• x-schemabound-runtime-augmentation-key when they want to reference a stable application-facing key

Additional headers help SCHEMABOUND match the right augmentation and preserve the meaning of the request:

• x-schemabound-tool-name
• x-schemabound-tool-intent
• x-schemabound-user-id
• x-schemabound-organization-id
• x-schemabound-domain-tags
• x-schemabound-table-names

Distributed Tracing Headers

Two additional headers carry W3C trace-context identifiers for distributed tracing correlation. When present, these values are propagated into every AuditEventEnvelope and appear as metadata.trace_uid and metadata.span_uid in every OCSF audit record.

Send these headers when your upstream instrumentation (OpenTelemetry, Jaeger, or similar) already generates trace context. SCHEMABOUND will propagate them through execution events so audit records and OTLP spans can be joined in your observability platform.

What Clients Should Send

Send the smallest stable set of metadata that explains why the request exists and which business boundary it belongs to.

Good examples include:

• the name of the calling product surface or tool
• the user or service identity associated with the request
• the tenant or organization boundary
• domain tags that explain business meaning
• table or resource hints when the execution path depends on them

What SCHEMABOUND Emits

SCHEMABOUND emits resolved augmentation identity into normal query and runtime events so downstream systems can observe which public context was selected.

Sensitive rendered content is intentionally separated from generic event metadata and reserved for dedicated audit handling.

Integration Guidance

Use runtime context when you want SCHEMABOUND behavior to stay aligned with application intent rather than just raw transport details.

Typical uses include:

• attaching product identity in a multi-surface application
• carrying organization context through service-to-service calls
• selecting augmentation rules for automation or assistant workflows
• keeping audit and observability signals consistent across clients

Control Plane Workflows — Conceptual Guide

TL;DR — The control plane gives SCHEMABOUND a structured way to track and execute multi-step agent workflows. Instead of issuing tool calls one at a time with no shared state, clients submit complete plans and drive execution step by step. Each step returns an LlmContextUpdate that carries tool output and schema changes back to the LLM for the next invocation.

Use this page if you need to: understand why stateful workflows exist, learn how plans/steps/LLM context updates work, or decide whether to adopt the control plane for your use case.

The control plane gives SCHEMABOUND a structured way to track and execute multi-step agent workflows. Instead of issuing tool calls one at a time with no shared state, a client can submit a complete plan and drive execution step by step, receiving a feedback object after each step that carries tool output and any schema changes back to the LLM for the next invocation.

Why a Control Plane

A single tool call is stateless. The agent asks a question, SCHEMABOUND answers it, and the conversation moves on. Most production workflows are not that simple — they involve dependent queries, operations that discover schema at runtime, and decisions that build on earlier results.

Without a control plane:

• the LLM must track intermediate state itself, which is unreliable across long conversations
• schema changes that occur mid-workflow reach the LLM late or not at all
• there is no stable record of what the agent intended versus what actually executed

The control plane solves this by making the plan a first-class object that persists through the full execution lifecycle.

Concepts

Plan

A plan is a named, versioned collection of steps with explicit dependency relationships. Steps declare their dependencies with depends_on; the control plane validates the dependency graph before any step executes and rejects cycles.

A submitted plan is assigned a stable plan_id that clients use for all subsequent operations.

Step

Each step in a plan corresponds to one tool call. A step carries:

• a tool_name and tool_intent that govern policy evaluation
• a query_template that may reference prior step output via the {{step.<id>.output}} syntax
• schema_table_hints that tell the control plane which tables to snapshot for schema diffing
• a depends_on list naming steps that must complete before this step can execute

LLM Context Update

When a step finishes, the control plane returns an LlmContextUpdate alongside the step result. This is the explicit feedback object the SDK passes to the next LLM API call.

It carries:

• tool_output_json — the serialised result of the step, ready to include in the next message
• schema_additions — a list of SchemaTableDelta entries (NEW, MODIFIED, or REMOVED) for any tables named in schema_table_hints that changed during step execution
• augmentation_hints — human-readable strings derived from schema deltas, ready to append to the system prompt

The LLM always sees the current schema state before choosing its next action, which means tool definitions stay accurate even when schema evolves mid-workflow.

Template Substitution

Query templates support {{step.<id>.output}} placeholders. The control plane resolves these server-side before calling the query service — the LLM does not need to construct final SQL or query strings directly.

For example, a step template like:

SELECT * FROM orders WHERE customer_id = {{step.lookup_customer.output}}

becomes a fully resolved query once the lookup_customer step has completed and its output is available.

Runtime Context Headers for Control Plane

Steps execute under the same gRPC metadata model as ordinary queries. Two additional headers carry control-plane identity:

These are emitted into query events alongside the standard session, user, and organization fields.

Event Integration

Control-plane events flow through the same global EventBus used by the rest of the runtime. Four new event variants are available to handlers:

Existing AuditLogHandler, QueryMetricsHandler, and SessionActivityHandler receive these events the same way they receive query events — no changes to handler registration are needed.

Schema Topology Integration (Enterprise)

When executing plan steps, the control plane consults schema topology information for foreign-key cascade awareness. This ensures that operations affecting referenced tables trigger appropriate cascade actions across dependent objects without manual orchestration. The topology graph is maintained by a background introspection binary and consulted during step execution to determine safe ordering of related operations.

Reference

For gRPC proto definitions, REST API endpoints, and the WorkflowOrchestrator trait contract, see Control Plane Reference.

Migration Management — Declarative DDL Revision Control for SCHEMABOUND

SCHEMABOUND ships a cross-language migration library that generates and applies DDL changes via a single Rust binary called sb-migrate. Every SDK (Rust, Python, .NET, TypeScript/Node.js) wraps this binary as a subprocess — no external migration tooling or database-specific engines required.

Why Declarative Migrations?

Traditional migrations are imperative: you write the exact SQL to apply and reverse each change by hand. This works until your schema has grown into dozens of tables with interdependent indexes, foreign keys, and constraints. At that point:

• Manual reversal becomes error-prone.
• Adding a column in one environment but forgetting to update it elsewhere causes drift.
• Schema diffs between environments are hard to audit or reproduce.

Declarative migrations flip the model: you describe what schema state you want, and sb-migrate computes the how. The same algorithm runs on every SDK — Python generates exactly the same SQL as .NET for identical snapshots.

Supported Dialects

The Binary: sb-migrate

The binary is built from the schemabound-migrations Rust crate. It accepts two invocation modes:

Clap Subcommands (Direct Use)

# Initialize the migration tracking table
./target/debug/sb-migrate init --dialect mysql

# Compute a diff between two schema files
./target/debug/sb-migrate diff --from current.json --to desired.json

# Apply a migration plan from JSON
./target/debug/sb-migrate apply --sql-file plan.json

JSON Stdin Protocol (SDK Use)

Each SDK encodes commands as JSON and writes them to stdin. The binary returns structured JSON on stdout:

echo '{"command":"init","dialect":"mysql"}' | sb-migrate
# → {"status":"success","code":0,"data":{"sql":"CREATE TABLE ..."}}

Invalid input or runtime errors produce a structured {"status":"error","code":N,"message":"..."} response with exit code 1.

Architecture

┌──────────────┐     JSON stdin      ┌─────────────┐
│   Python SDK │ ──────────────────▶ │ sb-migrate   │
│   .NET SDK   │                     │ (Rust crate) │
│ TypeScript   │                     │              │
│ Rust         │ ◀────────────────── │  diff_snapshots()
│              │     JSON stdout     │  plan_to_sql()
└──────────────┘                     └─────────────┘

The binary is a thin orchestration layer. All schema analysis runs in the schemabound-migrations library:

• Dialect registry — pluggable type mappers, parameter styles, and SQL generators per dialect.
• Diff engine — compares TableSnapshots to produce a MigrationPlan with typed steps (CreateTable, DropColumn, RenameColumn, etc.).
• Reverser — inverts plans for down migrations; falls back gracefully when reversal requires schema history.
• SQL generator — renders each step into dialect-specific SQL using the registered type mapper.

Migration Tracking Table

Each database that SCHEMABOUND manages carries a single tracking table (default schemabound_migrations) with columns:

CREATE TABLE IF NOT EXISTS schemabound_migrations (
    revision   VARCHAR(64) PRIMARY KEY,
    name       VARCHAR(255) NOT NULL DEFAULT '',
    applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    rollback_sql TEXT,
    checksum   VARCHAR(64) NOT NULL DEFAULT ''
);

The table name is configurable per dialect via --table-name-override (Rust/CLI) or the equivalent SDK parameter. The tracking table records applied revisions and their associated rollback SQL so down migrations can be replayed safely.

Data Model

All four SDKs share an identical type model matching the Rust crate:

TableSnapshot          ──┬── columns: Vec<ColumnDef>
    name               │       name, sql_type, nullable, default, unique
    primary_key        └── indexes: Vec<IndexDef>
                         index.name, index.columns, index.unique
MigrationPlan          ── id, direction ("Up" | "Down"), steps
MigrationStep          ── kind (CreateTable | DropTable | AddColumn | ...)
                         data (step-specific payload)

Cross-Language Quick Start

Rust

See sdk/rust.md. The sb-migrate crate is published as part of the SCHEMABOUND family.

Python

from schemabound_sdk import MigrationEngine, table_snapshot, ColumnDef

engine = MigrationEngine(dialect="mysql")

# Initialize tracking table
result = engine.init()
print(result["data"]["sql"])  # CREATE TABLE IF NOT EXISTS ...

# Generate diff between current and desired schema
diff_result = engine.diff(
    to_schema=[
        table_snapshot(
            name="users",
            columns=[
                ColumnDef(name="id", sql_type="BIGINT", nullable=False, unique=True),
                ColumnDef(name="email", sql_type="VARCHAR(255)", nullable=False),
            ],
            primary_key=["id"],
        ),
    ]
)

# Apply the plan
from schemabound_sdk import MigrationPlan
plan = MigrationPlan(id=diff_result["data"]["id"], direction="Up")
engine.apply(plan)

.NET

using Schemabound.Migrations;

var engine = new MigrationEngine("mysql");

var initResult = engine.Init();
Console.WriteLine(initResult["sql"]);  // CREATE TABLE IF NOT EXISTS ...

var diffResult = await engine.Diff(toSchema: new List<TableSnapshot> {
    new TableSnapshot {
        Name = "users",
        Columns = new List<ColumnDef> {
            new ColumnDef { Name = "id", SqlType = "BIGINT", Nullable = false, Unique = true },
            new ColumnDef { Name = "email", SqlType = "VARCHAR(255)", Nullable = false }
        },
        PrimaryKey = new List<string> { "id" }
    }
});

var plan = new MigrationPlan { Id = (string)diffResult["id"], Direction = "Up" };
await engine.Apply(plan);

TypeScript / Node.js

import { MigrationEngine, TableSnapshot, ColumnDef } from "schemabound-ts";

const engine = new MigrationEngine({ dialect: "mysql" });

const initResult = await engine.init();
console.log(initResult.sql);  // CREATE TABLE IF NOT EXISTS ...

const diffResult = await engine.diff({
    toSchema: [{
        name: "users",
        columns: [
            { name: "id", sql_type: "BIGINT", nullable: false, unique: true },
            { name: "email", sql_type: "VARCHAR(255)", nullable: false }
        ],
        primary_key: ["id"]
    }] as TableSnapshot[]
});

const plan = { id: diffResult.id, direction: "Up" };
await engine.apply(plan);

Error Handling

All SDKs surface errors via typed exceptions that include the sb-migrate error code and a human-readable message:

Common error codes: 10 (diff failed), 20 (apply failed), 30 (not initialized), 40 (connection failed), 50 (already applied), 90 (invalid snapshot).

Configuration

The SDKs look for the sb-migrate binary in this order:

1. $SB_MIGRATE_BIN environment variable
2. Binary on $PATH (shutil.which / Process.Start / spawn)
3. Project-relative paths (bin/sb-migrate, <repo>/target/debug/sb-migrate, etc.)

For production deployments, set SB_MIGRATE_BIN to a known absolute path to avoid runtime lookup failures.

Where This Fits in the SCHEMABOUND Stack

Migration management is one of four pillars of SCHEMABOUND:

The migration library is independent of the gRPC runtime — you can use it standalone to manage schema evolution in any project that ships a Rust binary.

Contributing

See Contribution Workflow for the full TDD contract. The schemabound-migrations crate has its own test suite (39 tests) covering diff, reversal, SQL generation across dialects, and runner integration.

# Run all migration crate tests
cd libraries/schemabound-migrations && cargo test --tests

Augmenting Prompts with Agent Memory

This guide shows how to inject session memory into your prompt hooks so agents carry prior context without manual retrieval or serialization.

How Prompt Hook Augmentation Works

When a prompt hook resolve request includes a session_id, SCHEMABOUND automatically fetches the session’s memory entries and makes them available as {{memory_context}} inside the hook template. The caller does not need to retrieve or serialize prior context manually.

POST /api/prompt-hooks/:id/resolve
Content-Type: application/json

{
  "session_id": "abc-123",
  "context": { "user_id": "alice", "organization_id": "acme" }
}

The resolved template receives {{memory_context}} alongside the standard context variables before rendering.

Managing Memory Entries

List Active Sessions

GET /api/agent-sessions

Returns the list of all active sessions.

Response

{
  "data": [
    {
      "id": "abc-123",
      "created_at": "2026-04-19T10:00:00Z",
      "last_seen_at": "2026-04-19T10:42:00Z"
    }
  ]
}

Retrieve Session Memory

GET /api/agent-memory/:session_id

Returns all memory entries for a session in chronological order.

Response

{
  "data": [
    {
      "entry_type": "tool_call",
      "content": "{ \"tool\": \"query\", \"result\": \"...\" }",
      "created_at": "2026-04-19T10:05:00Z"
    }
  ]
}

Append a Memory Entry

POST /api/agent-memory/:session_id
Content-Type: application/json

{
  "entry_type": "observation",
  "content": "User confirmed the report looked correct."
}

Appends a new entry to the session’s memory store. All responses follow the { data: ... } envelope used by the rest of the SCHEMABOUND API.

Frontend Dashboard

The Agent Memory dashboard provides:

• Session list — all active sessions with timestamps
• Memory detail — selecting a session shows its entries in order, with entry type and content

mTLS Configuration

SCHEMABOUND supports mutual TLS authentication via the schemabound-certgen binary and runtime PEM loading. This section covers setup, usage, and configuration for production and development deployments.

certgen Binary

The schemabound-certgen CLI generates a certificate authority (CA), server certificates, and client certificates required for mTLS. It is the supported tool for generating all certificate material used by SCHEMABOUND services.

Installation

Build from source:

cargo build --release -p schemabound-certgen
cp target/release/schemabound-certgen /usr/local/bin/

Or use a release binary from the project releases page.

Generating Certificates

Generate a full mTLS certificate chain:

schemabound-certgen generate \
  --output-dir ./certs \
  --ca-name "SCHEMABOUND CA" \
  --server-cn "myservice.local" \
  --client-cn "admin-client"

This produces:

Customizing Certificates

Use --help for full option listing. Common options:

schemabound-certgen generate --help

• --output-dir — Directory to write certificates (default: ./certs)
• --ca-name — CN for the root CA (default: "SCHEMABOUND CA")
• --server-cn — Common name for server certificate (default: "localhost")
• --client-cn — Common name for client certificate (default: "client")
• --days — Certificate validity in days (default: 365)

Runtime Configuration

Services load certificates from environment variables or files at startup. The runtime validates PEM format and rejects malformed material with a clear error message.

Environment Variables

Loading from Files

Point the environment variables at files generated by schemabound-certgen:

export SCHEMABOUND_MTLS_CA_CERT=./certs/ca.crt
export SCHEMABOUND_MTLS_SERVER_CERT=./certs/server.crt
export SCHEMABOUND_MTLS_SERVER_KEY=./certs/server.key
export SCHEMABOUND_MTLS_CLIENT_CA_CERT=./certs/ca.crt

Dev Mode Bypass

During development, skip client certificate verification with:

export SCHEMABOUND_MTLS_DEV_MODE=true

This disables mutual TLS enforcement for the client verification step while still allowing server-side mTLS to function. Do not use in production.

Integration With gRPC

The runtime’s gRPC interceptor automatically enforces mTLS when certificates are configured. Client certificates are verified against the CA bundle on every incoming connection. Server certificates are presented during outbound connections to other SCHEMABOUND services.

No code changes are required — certificate configuration is purely environmental:

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

let server = grpc::build_server()
    .with_mtls(ca_cert_path, server_cert_path, server_key_path)?;
server.serve().await?;
}

Production Checklist

• Use a dedicated CA for production (do not reuse development certificates)
• Store private keys in a secrets manager or encrypted vault
• Set certificate expiry alerts (use --days appropriately)
• Rotate client certificates on employee offboarding
• Verify all services present valid client certificates before accepting connections
• Disable SCHEMABOUND_MTLS_DEV_MODE in production deployments

JWT Configuration

TL;DR — SCHEMABOUND rotates JWT signing keys without downtime by accepting a comma-separated list via SCHEMABOUND_JWT_SECRETS. New tokens are signed with the last entry; old entries remain valid until explicitly removed. Supports HS256, RS256, and ES256 algorithms configured per-issuer via JWT_ALGORITHM.

Use this page if you need to: configure JWT secret rotation for zero-downtime key changes, set up OIDC token validation against external identity providers (Entra ID, Okta, Keycloak), or troubleshoot expired/invalid JWT errors.

Configuration Variables

Rolling Key Rotation

SCHEMABOUND supports zero-downtime JWT secret rotation by accepting multiple secrets in a single configuration. The runtime evaluates keys in order from newest to oldest during validation; the last entry is used for new token signing while earlier entries remain active for validating tokens issued before rotation.

# Before rotation (single key)
SCHEMABOUND_JWT_SECRETS=old_secret_key_here JWT_ALGORITHM=HS256

# During rotation (two keys — old validates, new signs)
SCHEMABOUND_JWT_SECRETS=new_key_abc123,old_secret_key_here JWT_ALGORITHM=HS256

# After rotation complete (single key again)
SCHEMABOUND_JWT_SECRETS=new_key_abc123 JWT_ALGORITHM=HS256

Rotation Procedure

1. Generate a new signing secret using your preferred secure generator (e.g., openssl rand -hex 32)
2. Add the new key to the front of SCHEMABOUND_JWT_SECRETS while keeping the old key at the end
3. Restart SCHEMABOUND (or trigger a hot-reload via admin endpoint) — both keys are now active for validation; new tokens sign with the front entry
4. Wait until all previously-issued tokens have expired (check exp claim)
5. Remove the old key from the end of SCHEMABOUND_JWT_SECRETS and restart

External Identity Provider Verification

When SCHEMABOUND validates JWTs issued by external IdPs (Entra ID, Okta, Keycloak), it fetches public keys from the provider’s JWKS endpoint rather than using symmetric secrets:

# OIDC issuer URL for JWKS discovery
SCHEMABOUND_OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0

# Or explicit JWKS endpoint URL (if not discoverable via OIDC)
SCHEMABOUND_JWKS_ENDPOINT=https://login.microsoftonline.com/common/discovery/v2.0/keys

Public keys are cached in memory and refreshed on a configurable interval (SCHEMABOUND_JWKS_CACHE_TTL, default 1 hour). Expired cache entries trigger an async refresh without blocking request processing.

Algorithm Selection

Troubleshooting

“Invalid signature” errors after key rotation

If clients report invalid_signature after adding a new key to SCHEMABOUND_JWT_SECRETS, verify:

1. The old key is still listed at the end of the comma-separated list
2. No leading/trailing whitespace in individual keys
3. The restart completed before new tokens were issued (check SCHEMABOUND logs for “JWT secrets loaded” message)

Expired token errors from IdP-issued JWTs

External IdP tokens have fixed expiration windows (typically 1 hour). If SCHEMABOUND receives token_expired responses but the IdP says the token is valid:

1. Check system clock synchronization — NTP drift causes timestamp validation failures
2. Verify SCHEMABOUND_OIDC_ISSUER matches the IdP’s actual issuer URL (trailing slashes matter)

API Key Management (stub)

This guide will cover:

• Setting up the Dolt-backed api_keys registry with SHA-256 hashed keys
• Scoping permissions per client via the permissions JSONB column
• Key rotation workflow using the admin API (POST /admin/api-keys/{id}/rotate)
• Per-key rate limiting configuration via api_key_rate_limits table

LDAP Sync (stub)

This guide will cover:

• Configuring LDAPS connections on port 636 with CA bundle validation
• Enabling StartTLS on port 389 for environments that cannot use LDAPS directly
• Resolving posixAccount users and uniqueMember DN-based group membership
• Recursive nested group resolution via transitive closure computation

LDAP Group-to-RBAC Role Mapping (stub)

This guide will cover:

• Configuring %cn= rules to map LDAP groups to SCHEMABOUND roles
• Conditional role assignment based on OU membership
• Storing role mappings in the Dolt-backed ldap_role_mappings table
• Integrating with the existing RBAC engine for real-time permission evaluation

Session Management (stub)

This guide will cover:

• Configuring the token invalidation store for immediate session revocation
• Implementing logout flows that invalidate JWTs without waiting for expiration
• Monitoring active sessions via the admin dashboard
• Integrating with OIDC provider token introspection endpoints

SCIM Provisioning (stub)

This guide will cover:

• Enabling the built-in SCIM v2 server for automated user/group provisioning
• Configuring SCIM endpoints (/scim/v2/Users, /scim/v2/Groups)
• Mapping SCIM attributes to SCHEMABOUND identity fields
• Integrating with external IdPs (Entra ID, Okta) for Just-In-Time (JIT) provisioning

Casbin ABAC Integration (stub)

This guide will cover:

• Migrating from the current RBAC model to Casbin Attribute-Based Access Control (ABAC)
• Defining ABAC policies in casbin_model.conf and casbin_policy.csv
• Evaluating permissions against dynamic attributes (org_id, resource_owner, time_of_day)
• Backward compatibility with existing RBAC roles during migration

Host Hardening: SSSD and PAM (stub)

This guide will cover:

• Generating /etc/sssd/sssd.conf templates for LDAP/AD integration
• Configuring nsswitch.conf for passwd, group, and shadow lookups via SSSD
• Setting up the PAM stack (pam_unix.so sufficient + pam_sss.so use_first_pass)
• Hardening host configuration for air-gap deployments

Audit Logging and AI-SPM Integration

TL;DR — Every agent action in SCHEMABOUND is captured in a tamper-evident SHA-256 hash chain and exported via MultiTransportExporter to SIEM platforms, HTTP webhooks, or rotating log files. The pipeline treats adversarial prompt injections, LLM jailbreak attempts, and unauthorized role escalation as first-class security signals alongside conventional access-control events.

Use this page if you need to: configure audit export destinations, understand the hash-chain integrity model, or integrate SCHEMABOUND with your SIEM platform (Splunk, Elastic, custom webhooks).

Key Configuration

Why This Matters

Agent-driven systems introduce risk that traditional application audit trails were not designed to capture: adversarial prompt injections, LLM jailbreak attempts, data exfiltration via template expressions, and unauthorized role escalation through natural language. The SCHEMABOUND audit pipeline treats these as first-class security signals alongside the conventional access-control and query-execution events.

Architecture

The audit system is composed of four interlocking parts:

 Client Request
       │
       ▼
 ┌─────────────────────┐
 │  InjectionGuard     │  ← scans input before gRPC executor sees it
 │  InputScannerHook   │
 └────────┬────────────┘
          │ PromptInjectionSignalRaised (if pattern matches)
          ▼
 ┌─────────────────────┐
 │  EventBus           │  ← global ordered handler + exporter chain
 │  (hash chain)       │
 └────────┬────────────┘
          │ AuditEventEnvelope (sequence, hash, trace_id, …)
          ▼
 ┌─────────────────────────────────────────────────────┐
 │  MultiTransportExporter                             │
 │  ├─ stderr (OCSF NDJSON or raw JSON)               │
 │  ├─ HTTP webhook  (SCHEMABOUND_AUDIT_WEBHOOK_URL)          │
 │  └─ rotating file (SCHEMABOUND_AUDIT_FILE_PATH)            │
 └─────────────────────────────────────────────────────┘

Tamper-Evident Hash Chain

Every exported audit envelope carries a SHA-256 hash chain that links each event to the one before it. This makes it possible for a downstream SIEM to detect gaps or mutations in the audit stream.

A missing sequence number or a hash that does not chain correctly from the previous record is strong evidence of log tampering.

Chain Integrity Verification (Enterprise)

SCHEMABOUND includes a background worker that continuously verifies audit log integrity by checking:

• Sequence monotonicity: Events are emitted in strict ascending order with no gaps.
• Hash continuity: Each event’s prev_hash matches the computed hash of the previous envelope.

When a breach is detected — whether from corruption, truncation, or intentional modification — the worker emits an AuditChainIntegrityBreach event that flows through the same exporter pipeline as regular audit records. This enables SIEM correlation and automated incident response.

See Data Resilience Workers for operational details.

OCSF v1.1 Output

All exports default to OCSF (Open Cybersecurity Schema Framework) v1.1. OCSF is the interchange format used by major SIEM and AI-SPM vendors including Amazon Security Lake, Microsoft Sentinel, Splunk, and Wiz.

Class Mapping

Severity Mapping

The unmapped OCSF field carries SCHEMABOUND-specific chain fields (roam_hash, roam_prev_hash, roam_sequence) that have no direct OCSF equivalent but are required for continuity verification. When trace correlation is present it is emitted under metadata.trace_uid and metadata.span_uid.

Transport Configuration

All transports are configured via environment variables and can be combined.

Stdout / Stderr

SCHEMABOUND_AUDIT_STDOUT=ocsf   # emit OCSF v1.1 NDJSON to stderr (default)
SCHEMABOUND_AUDIT_STDOUT=json   # emit raw AuditEventEnvelope JSON to stderr
SCHEMABOUND_AUDIT_STDOUT=off    # disable stderr output

HTTP Webhook

SCHEMABOUND_AUDIT_WEBHOOK_URL=https://siem.example.com/ingest

One OCSF record per HTTP POST with Content-Type: application/x-ndjson. The request is fire-and-forget — failures are silently discarded to keep the request path unblocked. Use an internal aggregation endpoint (Fluent Bit, Logstash, Vector) to buffer and retry if delivery guarantees are required.

Rotating File

SCHEMABOUND_AUDIT_FILE_PATH=/var/log/schemabound/audit.ndjson
SCHEMABOUND_AUDIT_FILE_MAX_MB=100    # rotate at 100 MB (default)

Appends one OCSF NDJSON record per line. When the file reaches SCHEMABOUND_AUDIT_FILE_MAX_MB it is renamed to <path>.1 and a new file is opened. One generation of rotation is kept; integrate with a log shipper for longer retention.

OTLP / Distributed Tracing

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

When this variable is set the backend initialises an OpenTelemetry SDK tracer provider with a Tokio-backed batch span exporter (HTTP/protobuf transport — opentelemetry-otlp with http-proto + reqwest-client features). Every HTTP request handled by AuditFairing creates a child span whose trace_id and span_id are captured and written into the AuditEventEnvelope before the envelope is dispatched when request trace context is available.

When the variable is absent the SDK is still initialised in no-op mode, so nothing is exported over the network. Audit envelopes only include trace_id / span_id when AuditFairing can derive them from propagated tracing context (for example, a valid traceparent header) or from the legacy headers it falls back to; requests without either source may not include those fields.

At process exit the provider is shut down gracefully, flushing any in-flight spans.

Collector example (docker-compose):

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports:
      - "4318:4318"   # OTLP HTTP
    command: ["--config=/etc/otel/config.yaml"]

# otel/config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  jaeger:
    endpoint: jaeger:14250
    tls:
      insecure: true
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger]

Prompt Injection Detection

The InjectionGuard scans every incoming query against a compiled set of regular expressions before the gRPC executor processes it.

Pattern Library

When a pattern matches, a PromptInjectionSignalRaised event is always emitted to the audit pipeline regardless of policy. What differs is whether the request continues:

Injection Policy

SCHEMABOUND_INJECTION_POLICY=observe   # record signal, allow request (default)
SCHEMABOUND_INJECTION_POLICY=block     # record signal, reject request when severity ≥ medium

Use observe during a rollout period to build a baseline of true-positive rates before switching to block. The detection signal is available to your SIEM in either mode.

What Gets Logged

The emitted PromptInjectionSignalRaised event includes:

• excerpt — first 500 characters of the input (truncated to limit PII surface)
• input_hash — SHA-256 of the full input string for forensic correlation
• patterns — list of matched pattern names
• severity — highest matched severity
• action_taken — "observed" or "blocked"
• All standard QueryRuntimeContext metadata (user_id, org_id, session_id, …)

Distributed Tracing Correlation

SCHEMABOUND accepts W3C trace-context headers and propagates them into every audit envelope. This allows audit records to be joined with OTLP spans in your observability platform.

OpenTelemetry (primary)

When OTEL_EXPORTER_OTLP_ENDPOINT is configured (or the no-op SDK is active) the AuditFairing extracts any incoming W3C traceparent header, creates a child tracing::Span, and reads the live trace_id / span_id from the active OTel context via current_trace_context(). Both values are written into every AuditEventEnvelope.

Legacy headers (fallback)

For clients that cannot inject traceparent the following proprietary headers are accepted as a fallback when no OTel context is available:

Both values appear in the AuditEventEnvelope (trace_id, span_id fields) and in the unmapped section of every OCSF record.

HTTP Request Audit (AuditFairing)

In addition to gRPC-level events, the SCHEMABOUND backend attaches an AuditFairing to every HTTP request. This records:

• request method and path
• response status code
• measured request duration in milliseconds
• user identity headers (x-schemabound-user-id, x-schemabound-organization-id)
• trace ID from x-schemabound-trace-id

These records are emitted as LlmToolCallAuditRecorded events (OCSF class 6005 — API Activity) and flow through the same MultiTransportExporter as all other audit events.

Registering an Audit Exporter

Any process that embeds the SCHEMABOUND event bus can attach additional exporters:

#![allow(unused)]
fn main() {
use schemabound::{get_event_bus, AuditExporter, AuditEventEnvelope};
use async_trait::async_trait;
use std::sync::Arc;

struct MySiemExporter;

#[async_trait]
impl AuditExporter for MySiemExporter {
    async fn export(&self, envelope: AuditEventEnvelope) {
        // serialize and forward to your SIEM
    }
}

get_event_bus().register_audit_exporter(Arc::new(MySiemExporter))?;
}

Exporters are called concurrently after every dispatched event. They do not appear in the synchronous handler chain and cannot block or short-circuit event processing.

SIEM Integration Notes

Amazon Security Lake (OCSF native)

SCHEMABOUND OCSF records are compatible with Security Lake’s custom source ingestion. Point SCHEMABOUND_AUDIT_WEBHOOK_URL at a Firehose delivery stream configured for OCSF v1.1.

Splunk

Use the Splunk HEC endpoint with SCHEMABOUND_AUDIT_WEBHOOK_URL. The OCSF JSON structure maps directly to Splunk’s _raw field with the CIM-compatible security_finding sourcetype.

Microsoft Sentinel

Route the NDJSON file output with the Azure Monitor Agent using the OCSF table schema, or use the webhook transport targeting a Data Collection Endpoint.

AI-SPM Vendors (Wiz, Lacework, Orca)

These vendors consume OCSF class 2004 (Security Finding) records for AI-specific threat modelling. The PromptInjectionSignalRaised events with severity, pattern names, and input hash give AI-SPM tools the raw material they need to build attack timeline views and posture scoring.

Security Considerations

• Input truncation: only the first 500 characters of a matched query are stored in the audit record. The full input is never persisted; only its SHA-256 hash is retained for forensic correlation.
• Fire-and-forget webhook: transport failures are silently discarded. Use a local sidecar aggregator (Fluent Bit, Vector) if delivery guarantees are a hard requirement.
• Hash chain integrity: chain verification is the consumer’s responsibility. SCHEMABOUND provides the chain fields; the SIEM or audit consumer should alert on gaps.
• Policy default is observe: SCHEMABOUND does not block traffic by default. Switching to block is an explicit operational decision that must be validated against false-positive rates in your environment before enabling in production.

Self-Healing Infrastructure

SCHEMABOUND includes a self-healing pipeline that monitors infrastructure services and automatically recovers from failures. This ensures high availability without manual intervention for transient issues such as network partitions, resource exhaustion, or dependency crashes.

Overview

The self-healing system consists of two components:

1. Health checker — Periodically probes registered infrastructure services (database instances, gRPC endpoints, audit log writers) and records their current state (Healthy, Degraded, or Failed).
2. Restart pipeline — When a service enters Failed state, the pipeline attempts automatic recovery using exponential backoff with configurable limits.

Health Monitoring

Services register themselves with the health checker at startup. The checker runs on a configurable interval (default: 30 seconds) and aggregates results into a unified view accessible via internal APIs.

State transitions follow these rules:

Automatic Recovery

When a service fails, the restart pipeline applies exponential backoff before attempting recovery:

• Base delay: 5 seconds (configurable)
• Maximum delay: 60 seconds (capped to prevent excessive waiting)
• Escalation threshold: After a configurable number of consecutive failures (default: 5), the system escalates and stops automatic retries, emitting an alert for human intervention.

The backoff formula is:

delay = min(base_delay * 2^attempt, max_delay)

Configuration

Recovery behavior is controlled via environment variables or configuration files:

Integration With Service Lifecycle

The self-healing pipeline integrates with the service lifecycle state machine. Services transition through states (Starting, Running, Stopping, Stopped) and the health checker observes these transitions to determine when restart attempts are safe to execute.

Restart attempts only proceed when the target service is in a non-running state, preventing conflicts with manual operations or ongoing graceful shutdowns.

Event Emission

The pipeline emits structured events for observability:

These events flow through the same event bus used by other SCHEMABOUND components and can be consumed by alerting systems or audit log exporters.

Manual Intervention

When escalation is triggered, operators can:

1. Inspect the service state via internal health APIs
2. Manually restart the failing service using standard operational procedures
3. Reset the failure counter after confirming stability

The system will resume automatic recovery once the failure count drops below the escalation threshold (typically after a successful health probe).

Event Publishing

SCHEMABOUND provides a trait-based event publishing system that lets you distribute domain events to external systems such as message queues, analytics pipelines, or compliance archives. The reference implementation uses Kafka for high-throughput pub/sub, but the abstraction supports any transport.

Trait Contract

The public SDK exposes an EventPublisher trait that implementations must satisfy:

#![allow(unused)]
fn main() {
use schemabound::eventing::{EventPublisher, PublishError};
use async_trait::async_trait;

#[async_trait]
pub trait EventPublisher: Send + Sync {
    async fn publish(&self, topic: &str, key: &[u8], value: &[u8]) -> Result<(), PublishError>;
    
    async fn close(&self);
}
}

• publish — Send an event to a named topic with optional key-based partitioning.
• close — Gracefully shut down the publisher (flush buffers, release connections).

Implementations are responsible for connection management, retry logic, and transport-specific error handling. The trait returns a generic PublishError that wraps underlying failures.

Reference Implementation: Kafka

The built-in KafkaEventPublisher implements the trait using Apache Kafka. It supports:

• Per-topic partitioning — Events are distributed across partitions based on configurable strategies (key-based, round-robin, or custom).
• Configurable consumer groups — When used as a subscriber, events can be consumed by named groups with offset management.
• Heartbeat timeout — Configurable heartbeat interval for membership renewal in consumer groups.

Configuration

The Kafka publisher loads configuration from environment variables:

Topic Partitioning by Organization

For multi-tenant deployments, the publisher supports per-organization topic partitioning. Events are published to topics named {prefix}-{org_id}-events, where prefix is configurable and org_id comes from the event’s runtime context.

This ensures:

• Isolation: Each organization’s events land in their own topic.
• Scalability: Topics can be distributed across multiple Kafka brokers.
• Compliance: Audit requirements that mandate per-org data separation are satisfied at the transport layer.

Using the Publisher

Register the publisher with SCHEMABOUND’s event bus:

#![allow(unused)]
fn main() {
use schemabound::eventing::{EventPublisher, KafkaEventPublisher};
use std::sync::Arc;

let kafka = Arc::new(KafkaEventPublisher::from_env()?);
schemabound::get_event_bus().register_publisher(kafka)?;
}

The publisher receives all events emitted on the bus and forwards them to the configured Kafka cluster.

Custom Implementations

To publish events to a different system (e.g., RabbitMQ, AWS SNS, or a custom HTTP webhook), implement EventPublisher for your type:

#![allow(unused)]
fn main() {
use schemabound::eventing::{EventPublisher, PublishError};
use async_trait::async_trait;

struct MyCustomPublisher { /* ... */ }

#[async_trait]
impl EventPublisher for MyCustomPublisher {
    async fn publish(&self, topic: &str, key: &[u8], value: &[u8]) -> Result<(), PublishError> {
        // Forward to your custom system.
        Ok(())
    }
    
    async fn close(&self) {
        // Release resources.
    }
}
}

Register it the same way as the Kafka implementation. The event bus does not care about the underlying transport — only that the trait contract is satisfied.

Error Handling

Publish failures are non-fatal by default: the event bus logs the error and continues processing other events. If you need strict delivery guarantees, implement retry logic within your EventPublisher and surface errors through the PublishError type so the caller can decide how to handle them (e.g., by triggering a dead-letter queue or alerting).

Performance Considerations

• Batch publishing: For high-throughput scenarios, consider buffering events in memory and flushing in batches. The trait does not enforce synchronous publishing — implementations can use internal queues.
• Partitioner selection: Choose a partitioner that aligns with your consumer’s parallelism needs. Key-based partitioning ensures ordering per key; round-robin distributes load evenly.
• Backpressure: If your Kafka cluster is under heavy load, the publisher should apply backpressure (e.g., by blocking or dropping events with a configurable policy) rather than queuing indefinitely in memory.

Gateway Routes (stub)

This guide will cover:

• Configuring API Gateway routing rules for SCHEMABOUND backend and frontend services
• Setting up TLS termination with internal CA certificates
• Routing strategies for multi-tenant deployments
• Integrating with Gitea Actions runners behind the gateway

Air-Gap Deployment (stub)

This guide will cover:

• Staging CA certificates and internal tools on Ventoy USB for offline bootstrap
• Building custom DinD base images with internal CA trust
• Configuring air-gap Docker registry mirrors for Rust/Node/Go dependencies
• Running the full SCHEMABOUND stack without internet access

AAU Billing Reference

Agentic Activity Unit Weight Table

The weight is resolved from the intent context key that the SCHEMABOUND middleware attaches to every LlmToolCallAuditRecorded event. When no explicit intent is present the weight is heuristically derived from the tool/function name (see aau_weight_from_tool_name in services/backend/src/billing.rs).

AAU Billing Heatmap

Interactive visualization of ORM model × intent governance cost distribution. Cell dimensions scale with cumulative AAU total so operators can immediately spot which models and intents drive the most overhead.

Note: This heatmap loads sample data by default. When a running SCHEMABOUND backend is available, replace SAMPLE_DATA in aau-heatmap.js with a fetch call to /api/billing/usage/heatmap.

Event Schema: usage_events Table

REST API Endpoints

All billing endpoints require the caller to be authorised as billing admin (see Authorization below).

GET /billing/usage

Returns daily AAU totals for the authenticated organisation.

Query parameters

Response

{
  "data": [
    {
      "date": "2026-04-30",
      "action_count": 42,
      "total_aau": 87.0,
      "total_cost_usd": 0.0
    }
  ]
}

GET /billing/usage/heatmap

Returns AAU totals grouped by ORM model x intent — the matrix consumed by the D3 heat map on the AAU Dashboard.

Response

{
  "data": [
    {
      "orm_model": "Person",
      "intent": "write_insert",
      "aau_weight": 3.0,
      "total_aau": 9.0,
      "action_count": 3
    }
  ]
}

POST /billing/setup-intent

Creates a Stripe SetupIntent so the frontend can securely collect card details. Requires STRIPE_SECRET_KEY in the server environment.

Request body

{ "customer_id": "cus_abc123" }

Response — returns id, client_secret, and customer from Stripe.

GET /billing/payment-methods

Lists saved Stripe payment methods for the authenticated admin session.

DELETE /billing/payment-methods/<pm_id>

Detaches a Stripe payment method by its pm_… identifier.

Authorization

Billing endpoints are protected by the BillingAdmin request guard. A request is accepted when either condition is true:

• X-User-Role header equals admin (case-insensitive), or
• X-User-Permissions header contains manage:billing (comma-separated list).

Requests that satisfy neither condition receive 403 Forbidden.

Control Plane Reference

gRPC Service Definition

The control plane is exposed as a gRPC service defined in schemabound-proto.

service ControlPlaneService {
  rpc SubmitPlan    (SubmitPlanRequest)         returns (SubmitPlanResponse);
  rpc GetPlanStatus (GetPlanStatusRequest)      returns (GetPlanStatusResponse);
  rpc ExecuteStep   (ExecuteStepRequest)        returns (ExecuteStepResponse);
  rpc CancelPlan    (CancelPlanRequest)         returns (CancelPlanResponse);
  rpc StreamPlanEvents (StreamPlanEventsRequest) returns (stream PlanEvent);
}

Submit a Plan

message SubmitPlanRequest {
  string session_id   = 1;
  string name         = 2;
  string description  = 3;
  repeated PlanStepDef steps = 4;
}

message PlanStepDef {
  string step_id              = 1;
  string name                 = 2;
  string tool_name            = 3;
  string intent               = 4;
  string query_template       = 5;
  repeated string depends_on         = 6;
  repeated string schema_table_hints = 7;
}

A successful response returns a plan_id. All subsequent calls reference this identifier.

Execute a Step

message ExecuteStepRequest {
  string plan_id = 1;
  string step_id = 2;
}

message ExecuteStepResponse {
  bool              success           = 1;
  StepStatus        step_result       = 2;
  LlmContextUpdate  llm_context_update = 3;
  string            error_message     = 4;
}

The llm_context_update field is the value to pass back to the LLM before it chooses the next step.

Stream Plan Events

message StreamPlanEventsRequest {
  string plan_id = 1;
}

message PlanEvent {
  string plan_id    = 1;
  string event_type = 2;
  string payload_json = 3;
  string timestamp  = 4;
}

Event types include PlanCreated, PlanStepExecuted, PlanCompleted, and PlanFailed.

REST API Endpoints

Create a Plan

POST /api/plans
Content-Type: application/json

Request body

{
  "session_id": "sess-abc123",
  "name": "Customer order lookup",
  "description": "Find customer then retrieve their orders",
  "steps": [
    {
      "id": "lookup_customer",
      "name": "Look up customer by email",
      "tool_name": "query_customers",
      "intent": "read_select",
      "query_template": "SELECT id FROM customers WHERE email = 'alice@example.com'",
      "depends_on": [],
      "schema_table_hints": ["customers"]
    },
    {
      "id": "get_orders",
      "name": "Get orders for customer",
      "tool_name": "query_orders",
      "intent": "read_select",
      "query_template": "SELECT * FROM orders WHERE customer_id = {{step.lookup_customer.output}}",
      "depends_on": ["lookup_customer"],
      "schema_table_hints": ["orders"]
    }
  ]
}

Response

{
  "data": {
    "plan_id": "plan-8f1c2b3d",
    "status": "pending"
  }
}

Get Plan Status

GET /api/plans/:plan_id

Response

{
  "data": {
    "plan_id": "plan-8f1c2b3d",
    "status": "running",
    "steps": [
      { "step_id": "lookup_customer", "status": "completed" },
      { "step_id": "get_orders",      "status": "pending"   }
    ]
  }
}

Execute a Step

POST /api/plans/:plan_id/steps/:step_id/execute

Response

{
  "data": {
    "step_result": {
      "step_id": "lookup_customer",
      "status": "completed",
      "row_count": 1,
      "executed_at": "2026-04-20T14:00:00Z"
    },
    "llm_context_update": {
      "plan_id": "plan-8f1c2b3d",
      "step_id": "lookup_customer",
      "tool_output_json": "{\"id\": 42}",
      "schema_additions": [],
      "augmentation_hints": []
    }
  }
}

Cancel a Plan

DELETE /api/plans/:plan_id

OSS Trait Contract

The WorkflowOrchestrator trait in schemabound-public defines the full public interface. Any implementation — including custom ones — must satisfy:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait WorkflowOrchestrator: Send + Sync {
    async fn create_plan(
        &self,
        session_id: &str,
        definition: PlanDefinition,
    ) -> Result<PlanRecord, String>;

    async fn get_plan(
        &self,
        plan_id: &str,
    ) -> Result<Option<PlanRecord>, String>;

    async fn execute_step(
        &self,
        plan_id: &str,
        step_id: &str,
        ctx: &QueryRuntimeContext,
    ) -> Result<(StepResult, LlmContextUpdate), String>;

    async fn cancel_plan(
        &self,
        plan_id: &str,
    ) -> Result<(), String>;
}
}

NoOpWorkflowOrchestrator is the default in OSS builds. It satisfies the trait boundary and returns an explicit error on any write operation, making the absence of a backing store visible rather than silent.

Error Registry

Typed error enums exposed by the SCHEMABOUND public API contract. All fallible operations return typed errors rather than boxed trait objects, enabling precise handling at call sites and clean propagation with ?.

All types implement thiserror::Error with stable Display messages. They are designed to map cleanly to gRPC Status codes at the service boundary.

Timeout Constant

All mapper operations share a single timeout constant:

#![allow(unused)]
fn main() {
use schemabound::mapper::DEFAULT_TIMEOUT_SECONDS; // 30
}

This constant governs LocalMapper, TcpMapper, and GrpcMapper connection and request timeouts. Override at the server or client level when your deployment requires different bounds.

Error Propagation Example

#![allow(unused)]
fn main() {
use schemabound::mapper::{LocalMapper, Mapper, DEFAULT_TIMEOUT_SECONDS};
use schemabound::error::MapperError;

async fn run_query(db_path: &str, sql: &str) -> Result<(), MapperError> {
    let mapper = LocalMapper::new(db_path)?;
    mapper.validate_query(sql).await?;
    mapper.execute_query(sql).await?;
    Ok(())
}
}

Event Pipeline

The SCHEMABOUND event pipeline is implemented as a Chain of Responsibility over the global EventBus. Every domain event — query execution, validation failures, session registration, trigger fires — flows through a registered sequence of handlers before any subscribers see it.

Handlers are synchronous, ordered, and can short-circuit the chain by returning HandleOutcome::Stop. The default pipeline always returns HandleOutcome::Continue so the full chain runs for every event.

Handler Trait

#![allow(unused)]
fn main() {
use schemabound::interceptor::{Event, EventHandler, HandleOutcome};

pub struct MyHandler;

impl EventHandler for MyHandler {
    fn handle(&self, event: &Event) -> HandleOutcome {
        println!("[my-handler] {}", event.event_type());
        HandleOutcome::Continue
    }
}
}

Register with the global bus:

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

get_event_bus().register_handler(Box::new(MyHandler))?;
}

Handlers are invoked in registration order for every dispatched event.

Built-In Handlers (schemabound::handlers)

AuditLogHandler

Writes a one-line JSON audit entry to stderr for every event. This is always the first handler registered in the default gRPC pipeline so that every domain event is recorded before downstream processing.

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

get_event_bus().register_handler(Box::new(AuditLogHandler))?;
// → [audit] {"event_type":"QueryExecuted","db_identifier":"...","query":"..."}
}

QueryMetricsHandler

Tracks cumulative counts of QueryExecuted, QueryValidationFailed, and QueryExecutionError events through lock-free atomic counters. Readable from any thread at any point.

#![allow(unused)]
fn main() {
use schemabound::{SharedHandler, handlers::QueryMetricsHandler};
use std::sync::Arc;

let metrics = Arc::new(QueryMetricsHandler::new());
get_event_bus().register_handler(Box::new(SharedHandler(Arc::clone(&metrics))))?;

// later — read from a health endpoint
let snap = metrics.snapshot();
println!("executed={} failures={} errors={}",
    snap.queries_executed, snap.validation_failures, snap.execution_errors);
}

SessionActivityHandler

Counts SessionRegistered events so the gRPC layer can expose a live session counter without a database round-trip.

#![allow(unused)]
fn main() {
use schemabound::{SharedHandler, handlers::SessionActivityHandler};
use std::sync::Arc;

let activity = Arc::new(SessionActivityHandler::new());
get_event_bus().register_handler(Box::new(SharedHandler(Arc::clone(&activity))))?;

println!("active sessions: {}", activity.session_count());
}

SharedHandler<T>

A newtype wrapper that lets an Arc<T: EventHandler> be registered with the bus without transferring ownership, so the same handle can be retained for metrics reads.

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

// Arc retained for reading; clone registered with bus
get_event_bus().register_handler(Box::new(SharedHandler(Arc::clone(&my_handler))))?;
}

Default Handler Chain

DefaultHandlerChain bundles QueryMetricsHandler and SessionActivityHandler into a single struct with pre-made Arc handles — the recommended starting point for gRPC services.

#![allow(unused)]
fn main() {
use schemabound::{AuditLogHandler, DefaultHandlerChain, SharedHandler, get_event_bus};

let chain = DefaultHandlerChain::new();
let bus = get_event_bus();

bus.register_handler(Box::new(AuditLogHandler))?;
bus.register_handler(Box::new(SharedHandler(Arc::clone(&chain.query_metrics))))?;
bus.register_handler(Box::new(SharedHandler(Arc::clone(&chain.session_activity))))?;

// Retain chain for health probes
let queries = chain.query_metrics.snapshot().queries_executed;
let sessions = chain.session_activity.session_count();
}

Handler vs. Subscriber

Use handlers when execution order or short-circuiting matters. Use subscribers for fire-and-forget side effects where order is irrelevant.

Event Reference

All events are variants of the Event enum. The table below shows which events each built-in handler processes:

For full details on LlmToolCallAuditRecorded and PromptInjectionSignalRaised, including OCSF class mapping, transport configuration, and injection policy, see Audit Logging and AI-SPM Integration.

Audit Exporters

In addition to synchronous handlers, SCHEMABOUND provides an async exporter pipeline that runs after every dispatch. Exporters receive an AuditEventEnvelope containing the full event, a tamper-evident SHA-256 hash chain, and distributed trace correlation fields.

Register an exporter alongside handlers:

#![allow(unused)]
fn main() {
use schemabound::{get_event_bus, AuditExporter, AuditEventEnvelope};
use async_trait::async_trait;
use std::sync::Arc;

struct MyExporter;

#[async_trait]
impl AuditExporter for MyExporter {
    async fn export(&self, envelope: AuditEventEnvelope) {
        // forward to SIEM, file, or webhook
    }
}

get_event_bus().register_audit_exporter(Arc::new(MyExporter))?;
}

The MultiTransportExporter in schemabound-backend is the reference implementation: it fans events to stderr (OCSF NDJSON), an HTTP webhook, and a rotating log file, all driven by environment variables.

LlmSchema Derive Macro

The LlmSchema derive macro — provided by the schemabound-schema crate — generates a JSON Schema description of any Rust struct whose fields are annotated with standard Serde attributes. This schema is used at runtime to build context-aware prompts and to expose entity structure to LLM tool-calls, gRPC clients, and the Python SDK.

How it works

#[derive(LlmSchema)] delegates to schemars::schema_for!() under the hood and exposes a single method:

#![allow(unused)]
fn main() {
pub fn llm_schema() -> schemars::schema::RootSchema
}

The returned RootSchema is fully JSON-serialisable and can be embedded directly in prompts, returned over gRPC, or published to the OpenAPI spec.

SeaORM integration (Rust)

SeaORM entity models are the primary target for LlmSchema. Add both LlmSchema and JsonSchema to your DeriveEntityModel derive list:

#![allow(unused)]
fn main() {
use roam_schema::LlmSchema;
use schemars::JsonSchema;

#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize, LlmSchema, JsonSchema)]
#[sea_orm(table_name = "organizations")]
pub struct Model {
    #[sea_orm(primary_key, auto_increment = false)]
    pub id: Uuid,
    pub name: String,
    pub slug: String,
    pub description: String,
    pub owner_id: String,
}
}

With this in place, the schema is available at runtime without reflection:

#![allow(unused)]
fn main() {
let schema = organization::Model::llm_schema();
let schema_json = serde_json::to_string_pretty(&schema).unwrap();
}

Registering with a prompt hook

Pass the JSON schema to a PromptHookSchemaContext when resolving a prompt:

#![allow(unused)]
fn main() {
let schema_json = serde_json::to_string(&organization::Model::llm_schema()).unwrap();

let request = PromptHookResolveRequest {
    schema_context: PromptHookSchemaContext {
        database_id: Some("prod-db".to_string()),
        table_names: vec!["organizations".to_string()],
        domain_tags: vec!["identity".to_string()],
    },
    ..Default::default()
};
}

The matching rules in your prompt hook YAML can reference table_names and domain_tags:

schema:
  table_names: ["organizations"]
  domain_tags: ["identity"]

SQLAlchemy integration (Python SDK)

The Python SDK exposes entity schemas through the SchemaboundClient.get_schema() gRPC call. You do not need to replicate SeaORM models in Python — the schema travels over the wire.

Installation

pip install schemabound-sdk
# or with uv
uv add schemabound-sdk

Fetching a schema

from schemabound_sdk import SchemaboundClient

client = SchemaboundClient(host="localhost", port=50051)

# Retrieve the JSON Schema for a specific entity table
schema = client.get_schema(table_name="organizations")
print(schema)
# → {"$schema": "http://json-schema.org/draft-07/schema#", "title": "Model", ...}

Using the schema with SQLAlchemy

The returned dict is a standard JSON Schema object. Pass it to your ORM model for dynamic validation or prompt-context injection:

import json
from sqlalchemy import create_engine, text
from schemabound_sdk import SchemaboundClient

client = SchemaboundClient(host="localhost", port=50051)
schema = client.get_schema(table_name="organizations")

# Validate a row dict against the schema (e.g. using jsonschema)
import jsonschema
jsonschema.validate(instance=row_dict, schema=schema)

# Or embed the schema directly in an LLM prompt
prompt_context = json.dumps(schema, indent=2)

Injecting schema into a prompt hook

from schemabound_sdk import SchemaboundClient, PromptHookResolveRequest, SchemaContext

client = SchemaboundClient(host="localhost", port=50051)

request = PromptHookResolveRequest(
    schema_context=SchemaContext(
        database_id="prod-db",
        table_names=["organizations"],
        domain_tags=["identity"],
    )
)

resolution = client.resolve_prompt_hook(request)
print(resolution.rendered_prompt)

Field-level annotations

All standard Serde rename / skip attributes are respected by schemars:

#![allow(unused)]
fn main() {
#[derive(LlmSchema, JsonSchema, Serialize, Deserialize)]
pub struct Model {
    pub id: Uuid,

    /// Human-readable display name
    pub name: String,

    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    #[serde(rename = "ownerId")]
    pub owner_id: String,
}
}

The generated schema will include the description from Rust doc-comments, honour rename, and mark description as non-required because it is Option<…>.

Supported crates

Enable optional features in Cargo.toml:

schemars = { version = "0.8", features = ["derive", "uuid", "chrono"] }

API reference

The live HTTP API exposes all route schemas via Swagger UI. When the backend is running:

• Swagger UI: http://localhost:8000/api/swagger
• OpenAPI JSON: http://localhost:8000/api/openapi.json

Metadata Introspection

SCHEMABOUND’s metadata introspection surface — exposed through the schemabound::mirror module — gives agents a deep, structured view of the underlying database schema. Beyond basic table-and-column enumeration, it surfaces triggers, user-defined types, and ORM field-mapping heuristics so that agents can reason about data contracts and change semantics without manual annotation.

What Is Introspected

The full model is returned as a SchemaModel:

#![allow(unused)]
fn main() {
pub struct SchemaModel {
    pub tables: Vec<Table>,
    pub user_defined_types: Vec<UserDefinedType>,
}
}

Trigger Discovery

Triggers represent procedural data-change logic embedded in the database. Surfacing them allows agents to warn about side-effects, model cascading writes, and fire TriggerFired events.

#![allow(unused)]
fn main() {
use schemabound::mirror::introspect_sqlite_path;

let schema = introspect_sqlite_path("path/to/database.db")?;
for table in &schema.tables {
    for trigger in &table.triggers {
        println!(
            "[{}] TRIGGER {} {} {} ON {}",
            table.name, trigger.name, trigger.timing, trigger.event, trigger.table_name
        );
        // timing: BEFORE | AFTER | INSTEAD OF
        // event:  INSERT | UPDATE | DELETE | UPDATE OF <col>
    }
}
}

Trigger Struct

#![allow(unused)]
fn main() {
pub struct Trigger {
    pub name: String,
    /// INSERT | UPDATE | DELETE | UPDATE OF <col>
    pub event: String,
    /// BEFORE | AFTER | INSTEAD OF
    pub timing: String,
    pub table_name: String,
    pub body: String,  // the raw CREATE TRIGGER body
}
}

TriggerFired Event (EventBus)

When the SCHEMABOUND runtime detects that a mutation query will fire a trigger, it emits a TriggerFired variant on the EventBus:

#![allow(unused)]
fn main() {
use schemabound::interceptor::{get_event_bus, Event};

get_event_bus().register_subscriber(Box::new(|event: &Event| {
    if let Event::TriggerFired { trigger_name, table_name, .. } = event {
        log::warn!("Trigger {} fired on {}", trigger_name, table_name);
    }
}))?;
}

User-Defined Types

SQLite encodes custom types as columns with CHECK constraints. The introspector discovers these and promotes them to first-class UserDefinedType entries.

#![allow(unused)]
fn main() {
pub struct UserDefinedType {
    pub name: String,
    pub base_type: String,             // TEXT, INTEGER, REAL, …
    pub check_constraint: Option<String>,
    pub nullable: bool,
    pub default_value: Option<String>,
}
}

Example — a table with an enum-like column:

CREATE TABLE orders (
    status TEXT NOT NULL CHECK(status IN ('pending','shipped','cancelled'))
);

The introspector produces:

{
  "name": "status",
  "base_type": "TEXT",
  "check_constraint": "status IN ('pending','shipped','cancelled')",
  "nullable": false,
  "default_value": null
}

This is also surfaced per-column via Column.enum_values.

ORM Field-Mapping Heuristics

Physical column names often differ from the logical names that application layers — Hibernate, Entity Framework, ActiveRecord — use. SCHEMABOUND detects the convention from naming patterns and generates a FieldMapping per column that appears to be ORM-managed.

#![allow(unused)]
fn main() {
pub struct FieldMapping {
    pub logical_name: String,
    pub physical_name: String,
    /// "hibernate" | "ef" | "ef_shadow"
    pub orm_convention: String,
    pub notes: Option<String>,
}
}

Convention Detection Rules

These heuristics enable agents to translate between LLM-generated column names and physical database column names without user annotations.

The MirrorProvider Trait

The MirrorProvider async trait lets you plug in any database backend:

#![allow(unused)]
fn main() {
#[async_trait::async_trait]
pub trait MirrorProvider: Send + Sync {
    async fn introspect_schema(&self) -> Result<SchemaModel, String>;
}
}

The built-in open-core implementation is SqliteMirrorProvider:

#![allow(unused)]
fn main() {
use schemabound::{MirrorProvider, SqliteMirrorProvider};

let provider = SqliteMirrorProvider::new("path/to/database.db");
let schema = provider.introspect_schema().await?;
}

MSSQL (Enterprise)

The emgen crate ships MssqlMirrorProvider, an enterprise implementation backed by SQL Server 2019+. It introspects INFORMATION_SCHEMA, sys.triggers, sys.types, and sys.indexes and maps them to the same SchemaModel surface as the SQLite provider.

#![allow(unused)]
fn main() {
use emgen::mirror::{MssqlConfig, MssqlMirrorProvider};
use schemabound::MirrorProvider;

let config = MssqlConfig {
    host:     "sqlserver.internal".to_string(),
    port:     1433,
    database: "MyApp".to_string(),
    username: "sa".to_string(),
    password: std::env::var("MSSQL_PASSWORD").unwrap(),
};
let provider = MssqlMirrorProvider::new(config);
let schema = provider.introspect_schema().await?;
}

The backend service auto-configures MssqlMirrorProvider from environment variables at startup:

When MSSQL_HOST is set, SchemaServiceImpl routes all schema requests through MssqlMirrorProvider and reports database_type: "MSSQL" in GetSchemaResponse. When unset, it falls back to the SQLite path.

To extend SCHEMABOUND to another database engine, implement MirrorProvider and inject it:

#![allow(unused)]
fn main() {
let executor = GrpcExecutor::builder()
    .mirror(MyPostgresMirrorProvider::new(&connection_string))
    .build()?;
}

Proto Surface

The introspected metadata is exposed over gRPC via GetSchemaResponse and GetTableResponse (see SchemaService proto):

message GetSchemaResponse {
  string schema_id                            = 1;
  string database_type                        = 2;
  string generated_at                         = 3;
  repeated TableDef tables                    = 4;
  repeated UserDefinedTypeDef user_defined_types = 5;
}

message GetTableResponse {
  string generated_at = 1;
  TableDef table      = 2;
}

message TableDef {
  string name                              = 1;
  repeated ColumnDef columns               = 2;
  repeated IndexDef indexes                = 3;   // is_unique distinguishes unique from regular
  repeated TriggerDef triggers             = 4;
  repeated FieldMappingDef field_mappings  = 5;
}

message TriggerDef {
  string name   = 1;
  string timing = 2;
  string event  = 3;
  string body   = 4;
}

message UserDefinedTypeDef {
  string name      = 1;
  string base_type = 2;
  repeated string variants = 3;
}

message FieldMappingDef {
  string column_name   = 1;
  string logical_name  = 2;
  string convention    = 3;
}

The Rust conversion function is table_to_table_def:

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

let proto_def = table_to_table_def(&schema.tables[0]);
}

Future Work

• PostgreSQL introspector — domain types, row-level security policies, event triggers
• Computed column detection — flag virtual/generated columns explicitly
• Partition metadata — surface range/list/hash partitioning from supported engines

Middleware Architecture

SCHEMABOUND middleware is the integration layer that lets products apply shared runtime context, identity-aware execution, and policy decisions close to the point where work actually happens.

Runtime Flow At The Boundary

At a high level, SCHEMABOUND middleware does three things for every participating request:

1. establish who or what is acting
2. attach the runtime context needed to make a safe decision
3. pass only validated execution downstream

The diagram below shows the logical shape of that flow.

Request Flow Diagram

This diagram shows the abstract pipeline a request moves through before execution continues.

sequenceDiagram
    participant Client as Client Application
    participant API as Product API / Service Boundary
    box "SCHEMABOUND Middleware Layer" #f9f9f9
        participant Identity as Identity Context
        participant Runtime as Runtime Interceptor
        participant Policy as Policy Review
    end
    participant Data as Downstream Service / Data Layer

    Note over Client, API: Request enters a SCHEMABOUND-enabled boundary
    Client->>API: 1. Submit request
    
    rect rgb(35, 35, 35)
        Note over API, Identity: Layer 1: Identity and request context
        API->>Identity: 2. Resolve identity and context
        Identity->>Identity: Match trusted identity inputs
        alt Identity Invalid
            Identity-->>API: 401 Unauthorized
            API-->>Client: Authentication error
        else Identity Valid
            Identity->>Runtime: 3. Attach runtime context
        end
    end

    rect rgb(40, 35, 35)
        Note over Runtime, Policy: Layer 2: Validation and policy review
        Runtime->>Runtime: Interpret request intent
        Runtime->>Policy: 4. Evaluate request
        Policy->>Policy: Apply execution rules
        
        alt Request Rejected
            Policy-->>Runtime: Block execution
            Runtime-->>API: 403 Forbidden
            API-->>Client: Request rejected
        else Request Approved
            Policy-->>Runtime: 5. Continue
        end
    end

    rect rgb(35, 40, 35)
        Note over Runtime, Data: Layer 3: Downstream execution
        Runtime->>Data: 6. Execute downstream work
        Data-->>Runtime: 7. Return result
    end

    Runtime-->>API: 8. Format response
    API-->>Client: 9. Final result

What This Layer Adds

1. Identity-aware context so requests carry the organization, user, or tool information needed for safe execution.
2. Interception at the right boundary so SCHEMABOUND can enrich or validate intent before it reaches core business logic.
3. Policy-aware execution so only approved operations continue into downstream systems.
4. Minimal disruption to existing systems so teams can integrate SCHEMABOUND without redesigning their application architecture.

Integration Models

SCHEMABOUND is designed to be protocol-agnostic and to sit as close as possible to the moment where intent becomes execution.

Model 1: Embedded Request Integration

This model fits products that already have an API layer and want SCHEMABOUND to participate in request handling without changing the rest of the application stack.

Common fit:

• existing APIs and service boundaries
• application teams adding runtime context and policy checks
• products that want SCHEMABOUND close to synchronous request handling

sequenceDiagram
    participant User as End User (UI)
    participant API as Product API
    participant OAM as SCHEMABOUND Middleware
    participant Runtime as SCHEMABOUND Runtime
    participant DB as Data Layer

    Note over User: 1. User action begins in the product
    User->>API: 2. API Request
    
    rect rgb(35, 35, 35)
        Note over API, OAM: Embedded request boundary
        API->>OAM: Intercept and enrich request
        OAM->>OAM: Resolve identity and runtime context
        
        par Runtime Coordination
            OAM--)Runtime: Emit runtime event
        and Request Validation
            OAM->>OAM: Evaluate request policy
        end
        
        alt Valid
            OAM->>API: Continue request
            API->>DB: Execute application work
            DB-->>API: Result
            API-->>User: Response
        else Rejected
            OAM-->>User: 403 Rejected Request
        end
    end

Model 2: Proxy Or Sidecar Boundary

This model fits systems that do not expose a clean application middleware layer but still need a controlled integration boundary.

Common fit:

• legacy applications
• direct data-access clients
• environments that need interception outside the primary application codebase

sequenceDiagram
    participant User as Existing Application
    participant Proxy as SCHEMABOUND Proxy / Sidecar
    participant Runtime as SCHEMABOUND Runtime
    participant DB as Data Layer
    participant Identity as Identity Source

    Note over User: 1. Existing system issues a request
    User->>Proxy: 2. Forward request to boundary layer
    
    rect rgb(40, 35, 35)
        Note over Proxy: Boundary interception
        Proxy->>Identity: Resolve permissions and context
        Proxy--)Runtime: Emit runtime event
        Proxy->>Proxy: Evaluate request rules
        
        alt Approved
            Proxy->>DB: Execute downstream request
            DB-->>Proxy: Rows
            Proxy-->>User: Result
        else Blocked
            Proxy-->>User: Rejected Request
        end
    end

Model 3: Hybrid Runtime Placement

This model fits teams that need local execution boundaries but still want shared governance, visibility, or centralized coordination patterns.

Common fit:

• high-compliance deployments
• organizations with mixed hosted and self-managed infrastructure
• teams that need execution inside their own perimeter

Model 4: Fully Self-Hosted Runtime

This model fits teams that want full control of runtime placement and operational ownership.

Common fit:

• air-gapped or highly restricted environments
• self-managed platform teams
• development and experimentation workflows built entirely on the public stack

sequenceDiagram
    participant Source as Product Event Source
    participant OAM as Local SCHEMABOUND Runtime
    participant Logic as Business Logic
    participant DB as System of Record

    Source->>OAM: Event / RPC Call
    
    rect rgb(35, 35, 45)
        Note over OAM: Local execution boundary
        OAM->>OAM: Apply local validation and context
        OAM->>Logic: Invoke Handler
    end

    Logic->>DB: Update State
    DB-->>Logic: Success
    Logic-->>OAM: Confirmation
    OAM-->>Source: Result

Choosing The Right Boundary

Pick the model that keeps SCHEMABOUND closest to the boundary where your system already makes trust and execution decisions. For most teams, that means starting with an SDK or embedded middleware pattern and expanding only when deployment constraints require it.

Python SDK Guide

Use the schemabound-python package when you want to integrate SCHEMABOUND into Python applications, automation workflows, and service-side tooling without giving up a script-friendly developer experience.

Why Choose The Python SDK

• Build Python services and internal tools that need direct access to SCHEMABOUND capabilities.
• Add SCHEMABOUND-backed workflow automation to notebooks, jobs, and lightweight application code.
• Move quickly with a familiar Python surface while staying aligned with the public SCHEMABOUND contract.

Installation

pip install schemabound-python

What You Get

The Python SDK gives you:

1. A Python-first client surface for integrating SCHEMABOUND into application and automation code.
2. Typed bindings over the public runtime model so Python code stays aligned with the supported SCHEMABOUND contract.
3. Utility helpers and examples that make it easier to adopt SCHEMABOUND in real product and workflow scenarios.

Quick Start

from schemabound_sdk import SchemaboundClient, SchemaboundDeclarativeBase

# Connect to SCHEMABOUND backend
client = SchemaboundClient(uri="localhost:50051")
client.ping()  # Verify connectivity

# Use as a SQLAlchemy declarative base for schema introspection
class User(SchemaboundDeclarativeBase):
    __tablename__ = "users"

This is the fastest path when you want to stand up a Python-based integration, validate connectivity, and start building application logic around SCHEMABOUND.

Runtime Augmentation

SCHEMABOUND runtime calls can carry runtime-augmentation selection metadata so your application can attach stable request context before validation or execution.

Use the public runtime headers when you need SCHEMABOUND behavior to reflect product context such as the calling tool, organization, or domain.

The key runtime headers are:

• x-schemabound-runtime-augmentation-id to reference a specific augmentation identifier
• x-schemabound-runtime-augmentation-key to reference a stable augmentation key
• x-schemabound-tool-name, x-schemabound-tool-intent, x-schemabound-user-id, x-schemabound-organization-id, x-schemabound-domain-tags, and x-schemabound-table-names to provide matching context

SCHEMABOUND emits resolved augmentation identity into normal query events, while sensitive rendered content remains reserved for dedicated audit handling.

Suggested Starting Points

• Building automation, internal tools, or orchestration logic in Python: start here.
• Prototyping a SCHEMABOUND integration before standardizing it across services: start here.
• Passing runtime context from application code into SCHEMABOUND execution paths: start with the runtime-augmentation headers above.

Contributing

For Rust Core Changes

If you need to change the shared public runtime or core SCHEMABOUND behavior:

1. File an issue in schemabound-public
2. Submit a PR to schemabound-public (see Contribution Workflow)
3. Once merged and exported, the change flows to schemabound-python automatically

For Python Layer Improvements

To improve the Python experience, add helpers, or expand documentation:

1. Fork schemabound-python
2. Create a feature branch
3. Make changes in libraries/schemabound-python/ (Python layer only)
4. Submit PR to schemabound-python/main
5. We’ll review and merge

Example:

# Add a utility function
# libraries/schemabound-python/schemabound_sdk/utils/config.py

def load_config_from_file(path: str) -> dict:
    """Load SCHEMABOUND configuration from YAML file."""
    ...

API Reference

See the full API docs for the Python package surface, method signatures, and integration details.

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

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

Core Concepts Glossary

Terms related to SCHEMABOUND’s architectural paradigm, schema operating modes, identity federation model, and billing units. These are the foundational concepts that differentiate SCHEMABOUND from traditional ORMs and data access layers.

Agentic Activity Unit (AAU)

A dimensionless measure of governance cost per tool call in SCHEMABOUND. AAU weights reflect the relative risk and computational overhead of different operation intents: Read = 1x, Write = 3x, Governed = 5x. The total AAU consumed by an agent session determines billing tier thresholds and rate limit windows.

See also: Intent Classification, Governance Cost Model

Bring Your Own Identity (BYOI)

A federated identity pattern where SCHEMABOUND trusts external identity providers (IdPs) such as Entra ID, Okta, LDAP, or any OIDC-compliant provider rather than maintaining its own user registry. BYOI enables SCHEMABOUND to integrate into existing enterprise directory structures without recreating permission systems from scratch.

See also: OIDC Token Validation, RBAC Mapping

Code-First Mode

A schema operating mode where database tables are registered explicitly in application code via Rust derive macros (#[derive(LlmSchema)]) or Python declarative bases. SCHEMABOUND enforces strict schema validation against registered models; unregistered tables are rejected at runtime unless the mode is switched to Hybrid or Data-First.

See also: Hybrid Mode, Data-First Mode

Control Plane

A first-class workflow execution layer in SCHEMABOUND that tracks and drives multi-step agent workflows through stateful plans. Each plan consists of named steps with explicit dependency relationships (depends_on); when a step completes, the control plane returns an LlmContextUpdate carrying tool output and schema changes back to the LLM for the next invocation.

See also: Plan, Step, Llm Context Update

Data-First Mode

A schema operating mode where SCHEMABOUND introspects an existing database at runtime and builds a read-only mirror of tables, columns, indexes, and triggers. Useful for integrating legacy databases without rewriting code; however, this mode provides no compile-time validation and relies on heuristics to detect ORM conventions (Hibernate camelCase vs EntityFramework PascalCase).

See also: Code-First Mode, Hybrid Mode

Governance Cost Model

The principle that every tool call in SCHEMABOUND carries a governance cost proportional to its risk profile. Read operations cost less than writes; administrative operations (schema changes, user management) cost more still. The model is implemented via AAU intent classification and enforced through policy evaluation before any query reaches the mapper layer.

See also: Agentic Activity Unit, Tool Contract Policy Engine

Hybrid Mode

A schema operating mode that combines Data-First introspection with Code-First registered models. Tables not explicitly registered in code are treated as Data-First (introspected at runtime); tables registered via derive macros are validated strictly against their declared schemas. This is the recommended production mode for incremental migration from legacy databases to SCHEMABOUND-managed schemas.

See also: Data-First Mode, Code-First Mode

Intent Classification

The process of categorizing a tool call’s intent (e.g., read_select, write_insert, admin) based on the SQL or query template being executed. Intent classification determines AAU weighting and policy enforcement severity — governed intents require approval workflows, while reads may pass through with minimal checking.

See also: Agentic Activity Unit, Tool Contract Policy Engine

Llm Context Update

A feedback object returned by the SCHEMABOUND control plane after each step in a multi-step plan completes. Carries tool_output_json (serialized result), schema_additions (list of NEW/MODIFIED/REMOVED tables from schema_table_hints), and augmentation_hints (human-readable strings for system prompt insertion). The LLM always sees current schema state before choosing its next action, ensuring tool definitions stay accurate even when schema evolves mid-workflow.

See also: Control Plane, Plan

Object Agent Mapping (OAM)

The architectural paradigm that maps agent intent to data operations rather than simply mapping objects to relational rows (as an ORM does). Where an ORM translates application code to SQL, OAM mediates what agents can see and do based on schema mode, identity context, injection guard filtering, and policy enforcement. SCHEMABOUND is the reference implementation of OAM.

See also: ORM, Schema Operating Modes

ORM (Object-Relational Mapper)

A programming technique that translates application objects into database rows and vice versa. Traditional ORMs (Hibernate, Entity Framework, SQLAlchemy) focus on object persistence; OAM extends this by adding intent mediation, identity context enrichment, and policy enforcement between the application layer and the data access layer.

See also: Object Agent Mapping, Schema Operating Modes

Plan

A named, versioned collection of steps with explicit dependency relationships in SCHEMABOUND’s control plane. Submitted via SubmitPlanRequest, a plan is assigned a stable plan_id that clients use for all subsequent operations (get status, execute step, cancel). Steps declare dependencies with depends_on; the control plane validates the dependency graph before any step executes and rejects cycles.

See also: Control Plane, Step

Schema Operating Modes

The three execution states that determine how SCHEMABOUND interacts with database schemas: Data-First (runtime introspection of existing databases), Code-First (strict validation against registered models), and Hybrid (combination of both). Mode selection affects security posture, development velocity, and migration complexity.

See also: Data-First Mode, Code-First Mode, Hybrid Mode

Step

A single tool call within a SCHEMABOUND control plane plan. Each step carries a tool_name, tool_intent (governing policy evaluation), a query_template that may reference prior step output via {{step.<id>.output}} syntax, and a depends_on list naming steps that must complete before this one executes. The control plane resolves template substitutions server-side before calling the query service.

See also: Control Plane, Plan

Security Terms Glossary

Terms related to SCHEMABOUND’s identity federation, authentication/authorization mechanisms, cryptographic protocols, and host hardening configurations. These terms are relevant when configuring mTLS, JWT rotation, LDAP sync, RBAC mapping, or SCIM provisioning.

API Key Registry

A persistent store of per-client API keys used for service-to-service authentication outside the OIDC/JWT flow. Each key carries a scoped set of permissions and can be rotated without affecting other clients. Keys are stored hashed (never plaintext) and rotated via the SCHEMABOUND_API_KEY_ROTATION schedule.

See also: OIDC Token Validation, JWT Secret Rotation

Casbin ABAC Integration

Integration with the Casbin library for Attribute-Based Access Control (ABAC). SCHEMABOUND’s RBAC roles are mapped to Casbin subject-object-action triples, enabling fine-grained policies that combine role membership with runtime attributes (organization ID, table name prefixes, intent type). Casbin policies are loaded at startup and hot-reloaded on change.

See also: RBAC Role Mapping, Policy Evaluation

Host Hardening: SSSD and PAM

Linux system hardening configuration using System Security Services Daemon (SSSD) for identity integration with LDAP/AD directories, combined with Pluggable Authentication Modules (PAM) for enforcing authentication policies. SCHEMABOUND deployment nodes are hardened following these settings to prevent credential theft, lateral movement, and privilege escalation attacks against the runtime itself.

See also: LDAP Sync, SCIM Provisioning

JWT Secret Rotation

The process of rotating JSON Web Token signing keys without downtime. SCHEMABOUND supports rolling key rotation via SCHEMABOUND_JWT_SECRETS (comma-separated list): new tokens are signed with the last entry; old entries remain valid until explicitly removed. This enables zero-downtime key rotation for HS256, RS256, and ES256 algorithms.

See also: OIDC Token Validation, API Key Registry

LDAP Group-to-RBAC Role Mapping

The mechanism that maps LDAP directory groups to SCHEMABOUND RBAC roles. When a user authenticates via LDAP, their group memberships are evaluated against the mapping rules defined in SCHEMABOUND_LDAP_GROUP_MAP; matched groups grant corresponding RBAC roles (e.g., cn=auditors,dc=example → role:audit_viewer). Groups not matching any rule receive no SCHEMABOUND permissions.

See also: LDAP Sync, RBAC Role Mapping

LDAP Sync

The periodic synchronization of user and group objects from an external LDAP or Active Directory directory into SCHEMABOUND’s identity layer. SCHEMABOUND uses SSSD for bind authentication and pulls group membership via LDAP filters; synced entities are used exclusively for RBAC role assignment, never as primary credentials.

See also: Bring Your Own Identity, LDAP Group-to-RBAC Role Mapping

mTLS Setup

Mutual Transport Layer Security configuration for service-to-service authentication. SCHEMABOUND uses schemabound-certgen to generate Certificate Authorities, server keys, and client bundles; clients present certificates during gRPC handshake and the server validates them against the CA before accepting any request. Development mode is available via SCHEMABOUND_MTLS_DEV_MODE.

See also: OIDC Token Validation, Host Hardening: SSSD and PAM

OIDC Token Validation

The process of validating OpenID Connect tokens presented by clients for authentication. SCHEMABOUND validates JWTs against the configured issuer’s JWKS endpoint, checks expiration (exp), issued-at (iat), and audience (aud) claims, and extracts identity context (user ID, organization) into QueryRuntimeContext. BYOI-compatible providers include Entra ID, Okta, Keycloak, and any standard OIDC endpoint.

See also: JWT Secret Rotation, Bring Your Own Identity

RBAC Role Mapping

The mechanism that assigns role memberships to authenticated users based on identity attributes (groups, claims, custom policies). SCHEMABOUND’s RBAC model supports hierarchical roles (admin > writer > reader), role inheritance, and deny-overrides. Roles are evaluated through the Casbin ABAC engine for fine-grained control over table access, intent permissions, and administrative operations.

See also: Casbin ABAC Integration, LDAP Group-to-RBAC Role Mapping

SCIM Provisioning

System for Cross-domain Identity Management (SCIM v2) server implementation within SCHEMABOUND. Enables automated user lifecycle management: when a user is created, updated, or deactivated in the external IdP, SCIM events trigger corresponding RBAC role assignments or revocations in SCHEMABOUND without manual intervention.

See also: LDAP Sync, Host Hardening: SSSD and PAM

Session Management

The lifecycle management of authenticated user sessions within SCHEMABOUND. Includes session creation on first successful authentication, token refresh on expiry, revocation on logout or security event, and audit logging via SessionActivityHandler. Sessions are scoped to organization boundaries; cross-organization session reuse is blocked by policy evaluation.

See also: OIDC Token Validation, RBAC Role Mapping

Operational Terms Glossary

Terms related to SCHEMABOUND’s runtime infrastructure, event publishing pipeline, self-healing workers, and observability systems. These terms are relevant when configuring the EventBus, tuning Auto-Rewind workers, setting up audit logging, or integrating with SIEM platforms.

Auto-Rewind Worker

A background data resilience worker in SCHEMABOUND that handles historical schema replay and topology refresh. When a table’s schema changes (columns added, indexes modified), Auto-Rewind replays the change through all dependent components — local mappers, TCP mappers, injection guard caches — ensuring consistency across the runtime without manual intervention.

See also: Chain Integrity Verification, Data Resilience Workers

Chain of Responsibility (CoR)

The handler pattern implemented by SCHEMABOUND’s EventBus. Every domain event — query execution, validation failures, session registration, trigger fires — flows through a registered sequence of handlers before any subscribers see it. Built-in CoR handlers include AuditLogHandler, QueryMetricsHandler, and SessionActivityHandler. Custom handlers can be registered via the SharedHandler trait.

See also: EventBus, Chain Integrity Verification

Chain Integrity Verification

A background worker that verifies the tamper-evident SHA-256 hash chain maintained by SCHEMABOUND’s audit logging pipeline. Each AuditEventEnvelope carries a sequence number and prev_hash; this worker periodically anchors verification at configurable depths (SCHEMABOUND_CHAIN_VERIFY_ANCHOR_DEPTH) to detect any tampering in the event stream before it reaches SIEM platforms.

See also: Auto-Rewind Worker, Audit Log Handler

Data Resilience Workers

The collective term for background workers that maintain SCHEMABOUND’s operational integrity: Auto-Rewind (schema topology refresh and historical replay) and Chain Integrity Verification (SHA-256 hash chain validation). Both run as independent goroutines with configurable exponential backoff (RESTART_BASE_DELAY_SECONDS) and are managed by the self-healing infrastructure health checker state machine.

See also: Auto-Rewind Worker, Chain Integrity Verification

EventBus

The typed event bus at the center of SCHEMABOUND’s runtime architecture. All domain events flow through the EventBus before reaching handlers or subscribers. Events are strongly-typed Rust enums (Event::QueryExecuted, Event::PlanCreated, etc.) that carry structured payloads; handlers implement the EventHandler trait and return a HandleOutcome indicating whether processing should continue down the chain.

See also: Chain of Responsibility, MultiTransport Exporter

Governance Cost Model

The principle that every tool call in SCHEMABOUND carries a governance cost proportional to its risk profile. Implemented via AAU intent classification (Read=1x, Write=3x, Governed=5x); enforced through policy evaluation before any query reaches the mapper layer. Total AAU consumed per session determines billing tier thresholds and rate limit windows.

See also: Agentic Activity Unit, Tool Contract Policy Engine

Llm Tool Call Audit Recorded Event

The core audit event emitted by SCHEMABOUND when a tool call completes (success or failure). Carries the full execution context: session ID, user identity, organization, traceparent W3C headers, tool name, intent classification, AAU weight, query template, result row count, and execution time. This event is what AuditLogHandler transforms into OCSF v1.1 format for SIEM export.

See also: EventBus, OCSF Format

MultiTransport Exporter

The fan-out mechanism that exports audit events to multiple destinations simultaneously. Configured via environment variables: SCHEMABOUND_AUDIT_LOG_DIR (rotating log files), SCHEMABOUND_AUDIT_WEBHOOK_URL (HTTP webhooks to SIEM platforms), and stderr for local development. The exporter is idempotent — if one destination fails, others still receive the event; failures are logged but never block the primary execution path.

See also: EventBus, OCSF Format

Query Metrics Handler

A built-in Chain of Responsibility handler that tracks query execution metrics for AAU billing and performance monitoring. Records: total queries per session, AAU consumed per intent type (read/write/governed), average execution time by tool name, and rate limit hits. Metrics are aggregated into the AAU Dashboard viewable at /billing/usage and exportable via the D3.js heatmap component for ORM model × intent cost analysis.

See also: Agentic Activity Unit, AAU Dashboard

Self-Healing Infrastructure

SCHEMABOUND’s automatic recovery mechanism for background workers and connection failures. Uses a health checker state machine that monitors Auto-Rewind and Chain Integrity worker liveness; on failure, triggers exponential backoff retry (RESTART_BASE_DELAY_SECONDS, max 5 attempts before escalating to operator alert). The state machine is topology-aware: it consults the schema graph during recovery to ensure dependent components are restarted in correct order.

See also: Data Resilience Workers, Auto-Rewind Worker

Session Activity Handler

A built-in Chain of Responsibility handler that captures per-session memory entries for SCHEMABOUND’s Agent Memory feature. Records observations, tool call results, and decision points as chronological history scoped to a session ID; history is retrievable via {{memory_context}} in prompt hooks so agents carry prior context across invocations without manual serialization.

See also: Agent Memory, Prompt Augmentation

Tool Contract Policy Engine

The component that evaluates tool-call contracts against registered policies before execution. Determines intent classification (read_select, write_insert, admin), applies AAU weighting based on intent, and enforces governance rules (approval workflows for governed intents, rate limits per organization). Policies are loaded at startup from SCHEMABOUND_POLICY_DIR and hot-reloaded on change without restart.

See also: Agentic Activity Unit, Intent Classification

Protocol Terms Glossary

Terms related to SCHEMABOUND’s communication protocols, serialization formats, and external integrations. These terms are relevant when implementing gRPC clients, parsing audit event payloads, or integrating with observability platforms.

gRPC

Google’s remote procedure call framework used as the primary transport protocol for SCHEMABOUND’s control plane and query execution APIs. The runtime listens on port 50051 by default; all service methods (SubmitPlan, ExecuteStep, GetSchema) are defined as protobuf message types in schemabound-proto. gRPC provides built-in streaming, compression, and mTLS authentication — the same transport used for both client-to-server queries and server-to-SIEM audit exports.

See also: protobuf, Execute Step Request

NDJSON (Newline-Delimited JSON)

The serialization format used by SCHEMABOUND’s audit event stream and MultiTransport Exporter. Each line of an NDJSON file or HTTP POST body contains a single complete JSON object representing one event; lines are delimited by \n. This format is streaming-friendly, parseable line-by-line without loading the full document into memory, and widely supported by SIEM platforms (Splunk, Elastic, Datadog) for log ingestion.

See also: OCSF Format, MultiTransport Exporter

OCSF (Open Cybersecurity Schema Framework)

An open standard for cybersecurity event data modeling maintained by the OCSF community. SCHEMABOUND exports audit events in OCSF v1.1 format, mapping internal QueryExecuted and LlmToolCallAuditRecorded events to OCSF Class 6003 (Database Activity). The framework provides standardized fields for timestamp, actor identity, target resource, metadata trace IDs, and custom extensions — ensuring SIEM platforms can correlate SCHEMABOUND events with other security telemetry without custom parsing.

See also: Llm Tool Call Audit Recorded Event, NDJSON Format

OCSF Class 6003

The specific OCSF schema class for “Database Activity” events. SCHEMABOUND maps every QueryExecuted and LlmToolCallAuditRecorded event to this class, populating standardized fields: activity_id (query action), database_name, table_name, actor_type (user/service), severity (informational/warning/critical based on AAU weight), and metadata (W3C traceparent headers for distributed tracing correlation).

See also: OCSF Format, Llm Tool Call Audit Recorded Event

protobuf

Protocol Buffers, Google’s IDL (Interface Definition Language) and serialization format. SCHEMABOUND defines all gRPC service contracts as .proto files in the schemabound-proto crate: ControlPlaneService, QueryService, SchemaService. Protobuf provides schema versioning via field numbers, binary encoding for efficient wire transfer, and language-specific code generation (Rust, Python, TypeScript, Go) via protoc plugins.

See also: gRPC, Execute Step Request

W3C Traceparent Header

The W3C distributed tracing standard header (traceparent) that identifies a request’s position within a larger trace across multiple services. SCHEMABOUND propagates traceparent through every audit event envelope emitted by the EventBus; when present, values appear as metadata.trace_uid and metadata.span_uid in OCSF records. Upstream instrumentation (OpenTelemetry, Jaeger) can inject these headers to join SCHEMABOUND events into existing observability platforms.

See also: OCSF Format, MultiTransport Exporter

API Reference

Use this page to choose the fastest way to integrate SCHEMABOUND into your product. Whether you are embedding SCHEMABOUND into an application, automating workflows, or standardizing service-to-service communication, the references below point to the public surfaces intended for real adoption.

Client SDKs

Choose the SDK that best matches your application stack.

Shared Contract

When you need a language-neutral integration surface, start with the protocol definitions.

Protobuf Definitions

HTTP REST API

The Rocket HTTP backend exposes a live, interactive API reference via Swagger UI. Use it to explore endpoints, inspect request/response schemas, and try calls directly from the browser.

Suggested Starting Points

• Building application logic in Python: start with the Python SDK.
• Shipping a service or platform integration on .NET: start with the .NET SDK.
• Building custom runtimes or native integrations: start with the Rust client crate.
• Aligning multiple clients or generating your own bindings: start with the protobuf definitions.
• Exploring or testing HTTP endpoints interactively: start with the Swagger UI.

Contribution Workflow

SCHEMABOUND accepts contributions across the public runtime, SDKs, and documentation. The goal of the workflow is simple: keep the public contract stable, keep changes reviewable, and make it clear where each kind of contribution belongs.

Choose The Right Repository

Start in the repository that owns the surface you want to improve.

• Use schemabound-public for shared runtime behavior, public contract changes, and core Rust functionality.
• Use schemabound-python for Python-specific helpers, bindings, packaging, and docs.
• Use schemabound-dotnet for .NET-specific helpers, bindings, packaging, and docs.

Contribution Flow

1. Fork the repository that matches your change.
2. Create a small, clearly named branch.
3. Add or update tests with the change.
4. Update documentation when the public workflow or contract changes.
5. Open a pull request against main.
6. Address review feedback and keep the branch current until merge.

Branch And PR Expectations

• Keep each change focused enough to review in one pass.
• Prefer small pull requests over large mixed-scope changes.
• If a unit test needs excessive mocking, simplify the production code before adding more scaffolding.
• If a test is called integration, it should talk to a real started runtime over the network.

Local Validation

Enable the repo-managed hooks after cloning when they are available:

make hooks-install

The local pre-commit path is intended to catch quality and test failures before you open a pull request.

CI Workflow

The CI system runs comprehensive checks on every push to main and pull request. The pipeline:

1. Quality — formatting, linting, and clippy across all components (backend, Rust SDKs, Python/.NET SDKs, frontend)
2. Tests — unit and integration tests for backend, schemabound-public, python-sdk, dotnet, frontend, and narrate run in parallel
3. Security Audit — cargo-audit scans dependencies for known vulnerabilities
4. Docs Build — verifies the documentation site builds successfully with mdBook

All jobs must pass before merge. The pipeline runs in under 10 minutes on a fresh ubuntu-latest runner.

External Contributor Setup

Step 1: Fork And Clone

Example for schemabound-public:

git clone https://github.com/<your-username>/schemabound-public.git
cd schemabound-public
git remote add upstream https://github.com/schemabound/schemabound-public.git

Step 2: Create A Branch

Use a descriptive branch name that matches the change you are making.

git checkout -b improve-runtime-context-docs

Step 3: Make The Change

Guidelines:

• write tests alongside behavior changes
• prefer repo Make targets where they exist
• keep unit tests deterministic and in-process
• keep integration tests runtime-backed and network-bound
• update docs when the public contract or contribution workflow changes

Step 4: Open A Pull Request

Push your branch and open a PR against upstream/main:

git push origin improve-runtime-context-docs

Include:

• a short description of the change
• the problem being solved
• how you validated the change
• any public contract impact or compatibility notes

Review Standards

SCHEMABOUND reviews focus on a few practical questions:

• does the change belong in this repository
• does the implementation stay within the intended public boundary
• do the tests match the behavior being claimed
• does the documentation still describe the public surface accurately

Common Paths

Fixing A Core Runtime Issue

Start with schemabound-public if the change affects shared runtime behavior, protocol shape, or public Rust functionality.

Improving A Python Integration

Start with schemabound-python if the change is specific to the Python developer experience, helper layer, or packaging surface.

Improving A .NET Integration

Start with schemabound-dotnet if the change is specific to the .NET developer experience, helper layer, or packaging surface.

Release Expectations

Pull requests validate changes. Releases publish them.

If you need publication timing or release behavior details, continue with Testing and Release Policy.

Testing and Release Policy

SCHEMABOUND treats testing and release discipline as part of the public contract. The goal is not just to ship code that works, but to ship public surfaces that are validated, predictable, and safe to adopt.

Test Layers

Each layer has a fixed contract. Violating that contract — mocking in integration tests, introducing I/O in unit tests, stubbing a container away in an E2E test — is a test smell, not a trade-off.

Unit Tests

Unit tests should stay fast, deterministic, and in-process.

Expectations:

• no live RPC or HTTP calls
• no containers
• no shared ports or database paths between test cases

Stubs and mocks are not the same thing. A stub returns a fixed value to put the system under test into a known state — that is acceptable. A mock asserts that the system under test calls it in a specific way (call count, argument shapes). If a unit test needs a mock, the production dependency has a design problem. Simplify the dependency before adding mock scaffolding.

If a unit test needs a large stub or mock hierarchy, treat that as a signal to simplify the production code, not to add more scaffolding.

Test isolation. Each test that starts a server or opens a database must use a unique address and path. Use atomic counters or unique temporary paths to avoid flaky collisions:

• Unique ports per test — allocate with an atomic counter, never hardcode a shared port.
• Unique database paths — use a helper like get_test_db_path() that returns a temp-scoped unique path per test.

Assertion style. Prefer exact value assertions over substring matching.

• Use matches!() for enum variant checks instead of .to_string().contains().
• Avoid snapshot tests — write explicit expected values so failures are immediately actionable.
• Assert on typed values, not serialized strings, wherever the types are available.

Integration Tests

Integration tests should validate real boundaries.

Expectations:

• real network requests over the actual protocol (TCP, gRPC, HTTP)
• a runtime that actually starts and listens on a real port
• real dependencies where the boundary matters — no shortcut local clients standing in for protocol behavior
• no stubs or mocks at any layer

If a test is named integration, it must talk to a real started runtime over the network. Tests that call in-process implementations directly are unit tests, not integration tests, regardless of what they are named.

End-To-End Tests

End-to-end tests validate a deployed environment from the outside. They are the right fit for rollout, wiring, secret, and networking concerns when that environment exists.

Expectations:

• fully deployed environment, nothing replaced or stubbed
• tests drive the system only through public entry points (API, CLI, browser)
• environment lifecycle (start, seed, teardown) is explicit and automated

CI Expectations

Pull requests to main should pass the quality profile relevant to the repository being changed. That can include:

• linting and formatting
• unit and integration tests
• build validation
• documentation builds
• coverage or maintainability gates where they add real signal
• dependency and security checks

SDK-specific maintainability gates are intentionally selective. They should exist where a codebase contains enough handwritten logic to justify them, not just because a language binding exists.

Local Validation

When available, enable the repo-managed hooks locally:

make hooks-install

The local hook path is intended to catch common failures before you open a pull request. It complements CI, but does not replace it.

CI Workflow

The CI system now runs all tests in parallel for better performance and stability. When changes are pushed to main or opened as pull requests, the system:

1. Runs quality checks (formatting, linting)
2. Starts required infrastructure (Dolt, LDAP)
3. Runs all component tests in parallel
4. Performs security audits and coverage checks
5. Builds documentation

This approach is more stable than the previous diff-based scoping because it ensures comprehensive test coverage without complex dependency tracking.

Release Discipline

Validation and publication are separate steps.

The expected release path is:

1. merge reviewed code to main
2. allow validation to complete on the merged revision
3. create the appropriate release tag when publication is intended

Current public release patterns include:

• public-v* for public subtree publication
• sdk-python-v* for Python SDK publication
• sdk-<language>-v* as the general form for future SDK release workflows

Why This Separation Exists

Separating merge validation from publication keeps the public SCHEMABOUND surface more predictable for adopters.

It ensures that:

• every published artifact passed review first
• release timing is deliberate rather than accidental
• public packages and docs stay aligned with validated source
• teams can reason about adoption risk more clearly

SCHEMABOUND Documentation — Editorial Style Guide

Consistency rules for terminology, formatting, and tone across all documentation assets. These guidelines ensure that readers encounter uniform language regardless of which page they’re reading, reducing cognitive friction when switching between conceptual explanations, how-to guides, and reference material.

Nomenclature Consistency

SCHEMABOUND has a specific set of canonical terms that must be used exactly as written. Deviating from these terms creates confusion for readers trying to look up information elsewhere in the documentation or in code comments.

* Use “OAM” only when referring to the paradigm itself; always introduce as “Object Agent Mapping (OAM)” on first use in any document.

Terminology Definitions

These terms appear frequently across SCHEMABOUND documentation and must be defined at first usage:

Formatting Rules

Tables

Use Markdown tables for configurations, environment variables, and OCSF class mappings — never bullet lists when presenting quantitative reference material. Tables make it easier for operators to scan and compare values during incident response or capacity planning.

| Variable | Default | Purpose |
|---|---|---|
| `SCHEMABOUND_AUDIT_STDOUT` | `ocsf` | Stderr output format: `ocsf`, `json`, or `off` |

Code Blocks

Always include a language identifier for syntax highlighting:

# Correct
```rust
let executor = GrpcExecutor::new(..);

Incorrect

let executor = GrpcExecutor::new(..);

Supported languages: `rust`, `python`, `typescript`, `go`, `bash` (for shell commands), `json` (for API payloads), `mermaid` (for architecture diagrams).

### API Endpoints

Use HTTP method + path format for all endpoint references. Always include the leading slash and quote the full path:

```markdown
# Correct
- `GET /billing/usage` returns daily AAU totals
- POST to `/api/plans/:plan_id/steps` creates a new step

# Incorrect
- GET billing usage returns...
- api.plans.plan_id.steps

Error Types

Format Rust enum variants using backtick formatting with the module path prefix:

# Correct
The executor returns `ExecutorError::ConnectionFailed` when the target database is unreachable.

# Incorrect
"connection failed error", "Executor Error: Connection Failed", ExecutorError::Connection_Failed

Callout Boxes (Summary Cards)

Use mdbook’s blockquote syntax for TL;DR summary cards at the top of complex pages. Always include both a one-paragraph overview and a “use this page if you need to…” section that helps readers decide whether to continue reading:

> **TL;DR** — [one-sentence overview of what this page covers]
> 
> **Use this page if you need to:** [3-5 bullet points describing reader goals this page addresses]

## Key Configuration (optional, for operational pages)

| Variable | Default | Purpose |
|---|---|---|

Tone and Voice

Do

• Be precise, technical, and concise. Assume the reader is a competent engineer who is unfamiliar with SCHEMABOUND specifics but understands general software architecture concepts.
• Use active voice: “SCHEMABOUND validates tokens against…” rather than “Tokens are validated by SCHEMABOUND…”
• Provide exact values when possible: “RESTART_BASE_DELAY_SECONDS defaults to 5” rather than “the delay is configurable.”

Don’t

• Use marketing language (“revolutionary”, “game-changing”, “best-in-class”). Technical documentation should inform, not persuade.
• Explain basic programming concepts (Rust lifetimes, Python decorators, TypeScript generics) — readers of this documentation are expected to know their primary language.
• Use ambiguous pronouns: “This feature allows you to…” should specify what “this feature” is.

Cross-Referencing

Use relative links within the documentation so that all references work whether viewed locally via mdbook serve or deployed to a static site. Never use absolute URLs unless linking to external resources (GitHub repositories, official spec documents).

# Correct — Relative links within docs
See [Control Plane Reference](../reference/control-plane-reference.md) for gRPC definitions.

# Incorrect — Absolute or broken paths
See https://github.com/schemabound/... 
See ../../docs/reference/control-plane.md (fragile to restructure)

External references are reserved for:

• GitHub repositories (https://github.com/schemabound/)
• Official specification documents (OIDC spec, OCSF schema registry)
• Third-party documentation (mdbook, Docusaurus, Mermaid) that readers may need for troubleshooting build issues

Review Checklist

Before submitting any PR that modifies SCHEMABOUND documentation, verify:

• All new terms follow the canonical nomenclature table above
• Code blocks include language identifiers
• API endpoints use METHOD /path format with leading slash
• Error types are formatted as `Module::EnumVariant`
• Tables used for configurations instead of bullet lists when presenting quantitative data
• Cross-references use relative links within the documentation tree
• Summary cards include both TL;DR paragraph and “use this page if you need to” section on complex pages