Struct DbSession 

pub struct DbSession<C: CanisterKind> { /* private fields */ }

DbSession

Session-scoped database handle with policy (debug, metrics) and execution routing.

Implementations

impl<C: CanisterKind> DbSession<C>

pub fn apply_schema( &self, proposal: &SchemaProposal, ) -> Result<SchemaChangeReceipt, InternalError>

Apply one exact source-keyed schema proposal through accepted catalog authority and return its durable idempotent receipt.

pub fn schema_application_target( &self, ) -> Result<SchemaApplicationTarget, InternalError>

Issue the opaque database/store identities and exact accepted head used to compose one optimistic schema proposal.

pub fn schema_application_receipt( &self, database_identity: TargetDatabaseIdentity, submission_key: &SchemaSubmissionKey, ) -> Result<Option<SchemaChangeReceipt>, InternalError>

Load one durable schema-application receipt by exact target and submission identity.

pub fn continue_schema_application( &self, job_id: SchemaChangeJobId, acknowledged_receipt: Option<u64>, ) -> Result<SchemaChangeProgress, InternalError>

Advance one pending schema application by at most one bounded activation step.

pub fn abort_schema_application( &self, job_id: SchemaChangeJobId, acknowledged_receipt: Option<u64>, ) -> Result<SchemaChangeProgress, InternalError>

Abort one pending schema application after acknowledging any retained finding page by exact sequence.

pub fn show_entities( &self, ) -> Result<Vec<EntityCatalogDescription>, InternalError>

Return one stable list of accepted runtime entity catalog entries.

pub fn show_stores(&self) -> Vec<StoreCatalogDescription>

Return one stable list of runtime-registered stores.

pub fn show_memory(&self) -> Vec<MemoryCatalogDescription>

Return one stable list of runtime-registered stable-memory allocations.

pub fn try_describe_entity_by_source_key( &self, entity_source: &str, ) -> Result<EntitySchemaDescription, InternalError>

Return one schema description selected by an immutable authored source key.

pub fn try_describe_entity_by_name( &self, entity: &str, ) -> Result<EntitySchemaDescription, InternalError>

Return one schema description selected by its accepted display name.

pub fn storage_report( &self, name_to_path: &[(&'static str, &'static str)], ) -> Result<StorageReport, InternalError>

Build one point-in-time storage report for observability endpoints.

pub fn storage_report_default(&self) -> Result<StorageReport, InternalError>

Build one point-in-time storage report using default entity-path labels.

impl<C: CanisterKind> DbSession<C>

pub fn execute_admin_integrity( &self, request: IntegrityCheckRequest, owner: IntegrityJobOwner, ) -> Result<IntegrityCheckResult, IntegrityDeepError>

Execute one trusted typed integrity request.

The caller must enforce controller or equivalent integrity-specific authorization before accepting caller-controlled requests. The owner must be a stable identity for that already-authorized caller or capability; possession of a job ID is never authorization.

Errors

Returns a typed protocol error for invalid requests, authorization ownership mismatches, and stale acknowledgements, or an internal error when accepted authority or physical inspection cannot be read safely.

impl<C: CanisterKind> DbSession<C>

pub fn execute_public_live_page( &self, request: &DynamicQuery, continuation: Option<&str>, ) -> Result<LiveQueryPageOutput, QueryError>

Execute one revision-tolerant bounded scalar page.

pub fn execute_public_dynamic_grouped_query( &self, request: &DynamicQuery, ) -> Result<GroupedQueryOutput, QueryError>

Execute one ordinary entity-name-driven bounded grouped read.

pub fn execute_trusted_dynamic_grouped_query( &self, request: &DynamicQuery, ) -> Result<GroupedQueryOutput, QueryError>

Execute one trusted entity-name-driven grouped read.

This bypasses ordinary public admission but retains accepted-schema planning, explicit grouped limits, cursor validation, and execution.

pub fn execute_trusted_live_page( &self, request: &DynamicQuery, continuation: Option<&str>, ) -> Result<LiveQueryPageOutput, QueryError>

Execute one trusted revision-tolerant bounded dynamic page.

Trusted execution bypasses public admission but retains the same physical and aggregate request budgets as every other read lane.

pub fn execute_public_exhaustive_page( &self, request: &DynamicQuery, continuation: Option<&str>, proof: Option<&ReadSetRevisionProof>, ) -> Result<ExhaustiveQueryPageOutput, ExhaustiveReadError>

Execute one revision-strict bounded dynamic page.

pub fn execute_trusted_exhaustive_page( &self, request: &DynamicQuery, continuation: Option<&str>, proof: Option<&ReadSetRevisionProof>, ) -> Result<ExhaustiveQueryPageOutput, ExhaustiveReadError>

Execute one trusted revision-strict bounded dynamic page.

impl<C: CanisterKind> DbSession<C>

pub fn capture_read_set_revision_proof( &self, entity_names: &[&str], ) -> Result<ReadSetRevisionProof, ExhaustiveReadError>

Capture one canonical proof covering every physical store behind the named accepted entities.

impl<C: CanisterKind> DbSession<C>

pub fn start_resumable_job( &self, job_id: ResumableJobId, proof: ReadSetRevisionProof, initial_application_state: Vec<u8>, ) -> Result<ResumableJobState, ResumableJobError>

Create one durable application-owned job in IcyDB’s excluded progress domain. Every protected source store must be journaled.

pub fn resumable_job_state( &self, job_id: ResumableJobId, ) -> Result<ResumableJobState, ResumableJobError>

Load the bounded current application state for one retained job.

pub fn acknowledge_resumable_job( &self, job_id: ResumableJobId, expected_sequence: u64, ) -> Result<(), ResumableJobError>

Remove one completed or invalidated job after the application has durably consumed its terminal result.

The expected sequence prevents acknowledgement of a replaced state. Repeating an acknowledgement after a lost reply succeeds when the job is already absent. Active jobs with remaining continuation fail closed.

pub fn compare_proof_and_advance<E>( &self, request: &ResumableJobAdvanceRequest, operation: impl FnOnce(&ResumableJobState) -> Result<ResumableJobAdvance, E>, ) -> Result<ResumableJobAdvanceReceipt, CompareProofAndAdvanceError<E>>

Execute at most one application page and atomically retain its next state after rechecking the complete source proof.

Replaying the same sequence and idempotency key returns the persisted receipt without invoking operation again. The closure is synchronous; no .await, timer, or external call can split proof comparison from the final progress write.

impl<C: CanisterKind> DbSession<C>

pub fn issue_typed_entity_binding( &self, entity_source_key: &str, field_requests: &[DynamicTypedFieldBindingRequest], ) -> Result<DynamicTypedEntityBinding, DynamicTypedBindingError>

Issue one opaque accepted binding for immutable generated source keys.

pub fn typed_entity_binding_is_current( &self, binding: &DynamicTypedEntityBinding, ) -> Result<bool, InternalError>

Verify that an opaque typed binding still names the exact accepted authority.

pub fn execute_trusted_dynamic_mutation( &self, request: &DynamicMutation, ) -> Result<DynamicMutationResult, InternalError>

Execute one trusted entity-name-driven structural mutation.

This lane resolves public values, defaults, generation, management, constraints, relations, and commit preparation from accepted schema. It never materializes a generated entity or invokes application validators/normalizers.

pub fn execute_trusted_dynamic_mutation_batch( &self, requests: Vec<DynamicMutation>, ) -> Result<DynamicMutationResult, InternalError>

Execute one bounded same-entity structural mutation batch atomically.

Every item binds to the same accepted catalog identity, shares one operation timestamp, and is projected to its public result before the commit marker can be published.

pub fn execute_trusted_dynamic_insert_batch( &self, entity: &str, patches: Vec<DynamicStructuralPatch>, ) -> Result<DynamicMutationResult, InternalError>

Execute one trusted atomic insert batch from entity-name-driven patches.

Every patch is lowered against the same accepted snapshot and shares one operation timestamp before the canonical structural batch owner stages any durable effect.

impl<C: CanisterKind> DbSession<C>

pub fn new( store: &'static LocalKey<StoreRegistry>, request_root: &RequestExecutionRoot, ) -> Self

Construct one session facade over a sealed runtime store registry.

pub const fn debug(self) -> Self

Enable debug execution behavior where supported by executors.

pub const fn metrics_sink(self, sink: &'static dyn MetricsSink) -> Self

Attach one metrics sink for all session-executed operations.