Crate cratestack 

CrateStack embedded facade — rusqlite + shared schema surface.

This crate is the embedded slice of the framework. It re-exports the shared schema / parser / policy / SQL surface plus the rusqlite 0.39 runtime, which compiles to native targets and to wasm32-unknown-unknown (via rusqlite’s transparent FFI switch to sqlite-wasm-rs).

It deliberately does not depend on cratestack-sqlx, cratestack-axum, or cratestack-client-rust. None of those compile on wasm32, and keeping them out of the dep graph also lets backend services depend on the official sqlx umbrella crate alongside the server facade without libsqlite3-sys collisions.

For backend services on Postgres, depend on cratestack-pg instead. The two crates are strictly disjoint by design.

Schema macros emit ::cratestack::* paths, so consumers rename this crate via Cargo’s package = field:

[dependencies]
cratestack = { package = "cratestack-sqlite", version = "0.4" }

Re-exports

pub use chrono;

pub use cratestack_client_rust as client_rust;

pub use regex;

pub use serde;

pub use serde_json;

pub use tracing;

pub use uuid;

pub use cratestack_rusqlite as rusqlite_backend;

pub use cratestack_rusqlite::rusqlite;

Modules

audit

Audit log primitives.

batch

Batch envelope.

codec

Pluggable codec + envelope traits used by the transport layer.

context

Request-scoped context: authenticated identity, structured principal, transport extensions, plus the AuthProvider trait that auth middlewares implement.

envelope

Signed envelope (HMAC-SHA-256).

error

CoolError — the framework’s error type, its 4xx/5xx HTTP mapping, and the public response envelope clients see on failure.

events

Model-event bus: typed created/updated/deleted envelopes that procedure handlers can subscribe to.

json

Schema-declared Json columns need a model-struct field type that’s the same on every backend so the same struct compiles on server and on embedded (including wasm32-unknown-unknown, which can’t depend on sqlx).

page

Generic paginated-page envelope used by every list route. The shape mirrors what generated clients consume.

projection

rpc

RPC binding wire types.

schema

Schema IR — the parsed shape of a .cstack file. Every IR node carries source-span back-pointers so consumers can map errors to positions in the original text.

transport

Transport-binding wire shapes shared by every generator (REST, RPC) and every server emitter.

validators

Field-level validators.

value

Backend-agnostic JSON-shaped value used throughout the framework (auth claims, audit payloads, RPC error details, schema config).

Macros

include_client_schema

HTTP client schema: model/input/procedure stubs for talking to a server over the wire. No DB, no router, no FromRow impls. Renamed from include_client_macro! in 0.3.0.

include_embedded_schema

Embedded ORM schema: rusqlite backend only. Compiles to native and to wasm32-unknown-unknown (via sqlite-wasm-rs). No sqlx, no axum, no procedures. Local apps that don’t need an RPC surface use this.

include_server_schema

Full server schema: sqlx Postgres backend, Cratestack runtime, axum router, procedures, events. Pass db = Postgres (only value currently supported; MySQL / SQLite-via-sqlx will land in a future release).

Structs

Attribute

AuditActor

AuditEvent

AuthBlock

BatchItemError

Public, safe-to-expose shape of a per-item failure. Mirrors crate::CoolErrorResponse without the optional details field — batch callers asking for per-item detail can repeat the operation singly against the failed item to get the full error envelope.

BatchItemResult

Per-item result inside a BatchResponse. The index is the item’s position in the original request, so clients can pair results with inputs even after server-side reordering (e.g. parallel batch_get fetches in the future).

BatchRequest

Wire envelope for POST /<model>/batch-* request bodies. Holds the items in a single field so the envelope can grow (e.g. a future client_request_id) without breaking deserialization.

BatchResponse

Wire envelope returned by every batch route. Always 200 OK at the HTTP layer; inspect summary.err (or scan results) to surface per-item failures to the user.

BatchSummary

Summary counts attached to every BatchResponse so callers can branch on aggregate status without scanning the result list.

CoalesceExpr

Left-hand operand of a coalesce-based filter — chain a comparator method to turn it into a FilterExpr.

CoalesceFilter

COALESCE(col_a, col_b, ...) <op> <value> — left-hand expression is the first non-null among the listed columns; right-hand side is a bound value via the usual FilterValue envelope. Lets schemas express the “ranked-fallback compare” pattern that shows up in outbox / scheduler tables, where a single row carries several time columns and the dispatcher wants the earliest non-null one.

ConfigBlock

ConfigEntry

CoolAuthIdentity

CoolContext

CoolErrorResponse

CoolEventBus

CoolEventEnvelope

CreateDefault

Datasource

DateTimeColumn

DecimalColumn

EnumDecl

EnumVariant

Field

FieldRef

Filter

HmacEnvelope

HMAC-SHA-256 backed envelope. Sealed messages are self-describing CBOR maps: signature recipients can decode the envelope, fetch the key by kid, and verify without out-of-band coordination.

InMemoryNonceStore

In-memory nonce store. One mutex; the working set is bounded by the clock-skew window — a 5-minute skew at 10k req/s caps at ~3M entries, which is fine. Production multi-replica deployments swap in Redis.

Json

JsonColumn

JsonTextPath

Left-hand operand of a json_get_text filter — chain a comparison method (.eq, .lt, .is_null, …) to produce a FilterExpr.

MixinDecl

Model

ModelColumn

ModelDescriptor

ModelEvent

MulticastAuditSink

Fan an audit event out to multiple sinks. Errors from any individual sink are aggregated into CoolError::Internal so a single failing downstream does not silently swallow problems with the others.

NoEnvelope

Pass-through envelope used when transport-layer signing is not required.

NoopAuditSink

Default sink that does nothing. The in-database audit table is treated as authoritative; downstream consumers are added by wrapping a different sink (or composing several).

OpDescriptor

Wire-shape of a single op in a transport rpc schema. See docs/design/rpc-transport.md for the full design — in short, an op is the dispatch unit shared by every RPC binding (HTTP unary, HTTP batch, HTTP stream, WebSocket). The macro emits one OpDescriptor per CRUD verb and per procedure when Schema.transport == TransportStyle::Rpc.

OrderClause

OwnedSchemaSummary

Page

PageInfo

PrincipalContext

PrincipalFacet

Procedure

ProcedureArg

ProcedurePolicy

Projection

Result of a .select(...)-projected read. Holds the model with only the selected columns populated — non-selected fields carry their type’s Default::default() value ("" for String, 0 for integers, None for Option<T>, etc.).

ReadPolicy

RelationFilter

RelationInclude

Typed handle for an .include(...) call on a query builder. Carries everything the runtime needs to issue the side-load query for a to-one relation: a function pointer that extracts the FK value from a parent row, and a static descriptor of the related model.

RequestContext

RouteTransportCapabilities

Wire-level capabilities for one route under a REST binding.

RouteTransportDescriptor

RusqliteRuntime

The on-device storage handle. Cheap to clone via Arc at the call site; the runtime itself is not Clone because the underlying connection shouldn’t be silently duplicated.

Schema

SchemaError

SchemaSummary

SealedEnvelope

SelectionQuery

SourceSpan

SpatialPoint

Builder returned by crate::point for assembling a spatial filter. Holds nothing but the lat/lng pair until a comparator is chained.

SqlColumnValue

SqlValueParam

Adapter that lets a borrowed SqlValue be bound by rusqlite.

StaticKeyProvider

In-memory KeyProvider for tests and single-tenant deployments. Banks running real workloads bring a backed implementation (KMS, Vault, HSM).

TypeDecl

TypeRef

UuidColumn

View

ViewDescriptor

ViewSource

Enums

AuditOperation

BatchItemStatus

Either a successful per-item outcome (Ok) or a per-item failure (Error). Serializes as a tagged enum with the discriminant in status:

ConflictTarget

Conflict target for an upsert. Defaults to the model’s primary key (matching the previous PK-only behavior). Columns lets callers upsert on an arbitrary unique tuple — most commonly a natural key that’s distinct from the PK (e.g. (owner_id, provider) on a per-owner-and-provider settings row, or (pairing_id, slot) on a per-slot envelope).

CoolError

CreateDefaultType

FilterExpr

FilterOp

JsonFilter

JSON / JSONB filter predicates. Two flavors:

ModelEventKind

NullOrder

Where NULLs sort relative to non-NULL values. PostgreSQL’s default is NULLS LAST for ASC and NULLS FIRST for DESC; SQLite’s default is NULLS FIRST for both. CrateStack pins the framework default to NULLS LAST so listings stay deterministic across backends and so soft-deleted rows (typed Option<DateTime> that surface as None for visible rows) don’t muscle their way to the top of every listing. Override per-clause via OrderClause::nulls_first when scheduler / outbox queries want fresh-as-null tasks at the head of the queue.

OpKind

PolicyExpr

PolicyLiteral

ProcedureKind

ProcedurePolicyExpr

ProcedurePolicyLiteral

ProcedurePredicate

ReadPredicate

RelationQuantifier

RusqliteError

Errors surfaced by the on-device runtime. Stays close to rusqlite::Error for now — wrapping in a cratestack-specific variant only when we cross the FFI boundary (Phase 5).

SortDirection

SpatialFilter

PostGIS spatial filter primitives. v1 ships two ops that cover the “is point inside this zone” / “is this point within radius of that zone” cases — the rest of the ST_* surface can land on demand.

SqlValue

TransactionIsolation

Transaction isolation level requested by a procedure via @isolation(...). Mirrors the PostgreSQL spec: lower variants tolerate more anomalies, higher ones cost more under contention. Banks running multi-row updates (transfers, postings) typically pick Serializable and pair it with retry-on-serialization-failure.

TransportStyle

Wire-shape the schema generates for. Picked once per schema (via the top-level transport rest|rpc directive) so generated servers and clients only carry one binding’s worth of surface.

TypeArity

Value

Constants

BATCH_MAX_ITEMS

Default upper bound on items in a single batch request. Server backends enforce this before any SQL runs and surface CoolError::Validation on the outer Result when exceeded. The cap is identical for all five batch operations; deviating per-op would invite footguns where batch_get accepts a list that batch_create of the same length rejects.

Traits

AuditSink

Pluggable audit sink. Implementations fan audit events out to downstream systems (Kafka topics, Redis pubsub, HTTP webhooks, S3 buckets) for long-term retention or SIEM ingestion. The in-database audit table written by cratestack_sqlx remains the canonical record; sinks are best-effort projections.

AuthProvider

CoolCodec

CoolEnvelope

CreateModelInput

FromPartialRusqliteRow

Partial-row decoder — mirrors [cratestack_sqlx::FromPartialPgRow] for the embedded backend. The macro emits this impl alongside FromRusqliteRow; users see it only as the bound on the typed builder’s T generic when they call .select(...).

FromRusqliteRow

Decode a model from a rusqlite row.

IntoColumnName

Anything that can name a single SQL column. Lets coalesce accept both bare &'static str column names and typed FieldRef handles, so callers don’t have to choose between schema-rooted typing and ad-hoc strings at the call site.

IntoSqlValue

KeyProvider

Resolves signing keys by kid (key id). Banks running multi-tenant or rotating keysets implement this so the envelope code never has to know the storage mechanism. Implementations must be constant- time for not-found vs wrong-tenant errors — never use the error message to leak whether a key id exists.

ModelPrimaryKey

Accessor for a model’s primary key. Implemented by the macro on every generated model struct so the batch operations can pair returned rows back to the position of their input PK in the request, producing a BatchItemResult with the right index and a NotFound entry for any requested PK that didn’t come back.

NonceStore

Tracks the nonces of sealed envelopes that have already been verified inside the clock-skew window, so a captured-and-replayed request gets rejected the second time. Banks running multi-replica deployments back this with Redis so the rejection holds cluster-wide.

ProcedureArgs

ProjectionDecoder

ReadSource

Anything a read-path query builder needs to plan and emit SQL.

UpdateModelInput

UpsertModelInput

Input shape for the upsert primitive — INSERT … ON CONFLICT (<pk>) DO UPDATE …. sql_values() must include the primary-key column (so the backend can target the conflict), and primary_key_value() exposes the PK separately so the runtime can issue a SELECT … FOR UPDATE before the upsert to drive Created vs. Updated event / audit semantics.

WriteSource

Anything a write-path query builder needs on top of ReadSource — create defaults, update / delete policy slots, audit + retention + versioning state, upsert column list, emitted event topics.

Functions

authorize_procedure

canonical_request_string

Canonical string assembled by the envelope signing path: METHOD\nPATH\nQUERY\nCONTENT-TYPE\nbody-hex. Both seal and verify reconstruct the same string from the same inputs.

coalesce

Build a COALESCE(...) left-hand operand. The returned CoalesceExpr carries the column list; chain a comparator method (.lte, .eq, .is_null, …) to produce a FilterExpr the query builders can consume.

event_topic

find_duplicate_position

Detect duplicate keys in a batch input, loud-failing the whole request when found. Returns the first duplicate (by position) so the surfaced error can name a specific offending index. Linear- time, allocation-only in proportion to the input length.

parse_cuid

parse_emit_attribute

parse_schema

parse_schema_file

parse_schema_named

point

Geographic point (WGS-84 lng/lat). The naming follows the PostGIS ST_MakePoint(x, y) convention — lng is the X axis (longitude), lat is the Y axis (latitude). Don’t accidentally swap them; the engine has no way to detect it and your filter will silently match points across the world.

validate_email

Pragmatic email check: requires exactly one @, non-empty local and domain parts, at least one . in the domain, and no whitespace. Not a full RFC 5322 grammar — that grammar admits forms (quoted local parts, IP literals) banks rarely accept anyway. Reject early; let real KYC flows do deeper validation.

validate_iso4217

ISO 4217 currency codes are 3 ASCII uppercase letters. We do not enforce the registered set here — that table churns and is downstream policy. Banks typically pin allowed currencies via a separate allow-list anyway.

validate_length

validate_range_decimal

Decimal-typed @range enforcement. The parser accepts integer bounds (@range(min: 0, max: 100)) on both Int and Decimal fields; the i64 bounds are promoted to Decimal here so monetary fields can declare the same shape as integer counters. Banks routinely write things like amount Decimal @range(min: 0) to forbid negative amounts at the framework layer — without this, the validator silently no-ops and out-of-range values reach the database.

validate_range_i64

validate_uri

Type Aliases

CoolBody

Body bytes carried through the transport layer.

CoolEventFuture

Decimal