Crate icydb 

Module: lib

Responsibility: public facade crate surface and generated-code wiring. Does not own: core execution, storage internals, or schema mutation semantics. Boundary: re-exports stable runtime and generated actor-wiring surfaces.

icydb

icydb is the public facade crate for the IcyDB runtime. It is the recommended dependency for downstream canister projects.

This crate exposes:

• the stable runtime surface used inside canister actor code,
• accepted-schema-bound database request and response types,
• and a small set of entry points that wire generated actor code.

Low-level execution, storage, and engine internals live in icydb-core and are re-exposed selectively through stable facade modules.

Crate layout

• build (host builds) Host-side build-script facade for generated actor glue. Downstream canister build.rs files should use this module rather than depending on lower-level implementation crates directly.

• model Application-model declarations, macros, reusable types, validation, and normalization. Runtime-enabled downstream crates should use this re-export instead of adding a second IcyDB package dependency.

• traits / types / value Stable runtime building blocks used by generated code.

• metrics (internal) Runtime metrics internals exposed for generated administration endpoints.

• Error / ErrorKind / ErrorOrigin Shared error types for generated code and runtime boundaries.

• db The public database façade: sessions, SQL/dynamic reads, structural mutations, and accepted-schema-bound typed adapters.

Generated SQL endpoints are controller-gated by default. A declaration may instead install one synchronous application read guard; neither form is an anonymous public read endpoint template.

The operational lane contract lives in docs/contracts/READ_ADMISSION.md. Endpoint migration recipes live in docs/guides/read-intent.md.

Preludes

• prelude Opinionated runtime prelude for canister actor code. Intended to be glob-imported in lib.rs to keep endpoints concise.

Internal boundaries

Generated code targets explicit facade surfaces (traits, db, and __macro) instead of a broad internal-export module.

Re-exports

pub use guards::ReadAuthorizationContext;

pub use guards::ReadAuthorizationDecision;

pub use guards::ReadAuthorizationGuard;

pub use guards::ReadAuthorizationSurface;

pub use icydb_model as model;

Modules

build

Host-side build-script facade for generated actor glue.

db

Module: db

diagnostic

Compact diagnostic identity for CLI and canister callers.

guards

Bounded application-supplied read-authorization contracts.

prelude

traits

Module: traits

value

Macros

build_canister

Generate one canister’s private actor module from its authored schema type.

db

Access the active request’s database session.

endpoints

Declare the complete fixed IcyDB endpoint surface exported by this canister.

start

Include the generated private actor module emitted by build_canister!.

Structs

ConstraintValidationFindingOutput

ConstraintValidationFindingOutput

ConstraintValuePath

ConstraintValuePath

DiagnosticFact

One bounded numeric parameter attached to a public IcyDB error.

Error

Error

ErrorCode

ErrorCode

ParseU256Error

Error returned when text or a Candid natural is outside the unsigned 256-bit domain.

QueryFieldDiagnostic

One bounded rejected query-field reference attached to a planning error.

U256

IcyDB-owned fixed-width unsigned 256-bit scalar.

Enums

ConstraintValuePathComponent

ConstraintValuePathComponent

ErrorKind

ErrorKind

ErrorOrigin

ErrorOrigin

QueryErrorKind

QueryErrorKind

RuntimeErrorKind

RuntimeErrorKind

Constants

VERSION

Attribute Macros

request_execution

Install one aggregate IcyDB execution root for a sync or async entry point.

test

Declare a synchronous unit test with the production request boundary.