Crate alkstore 

alkstore — the unified trait surface, value types, error model, and contract documentation of the store contract (ADR-001, ADR-008).

This crate is the contract artifact: no driver dependencies, ever. Engine crates (alkstore-sqlite, alkstore-postgres) depend on this crate and implement its traits.

This crate’s docs are part of the contract artifact (ADR-001 §1) — every public item carries doc text, and the missing-docs lint is part of the standing gates.

Structs

EnqueueOpts

Options for enqueueing a job (Queue::enqueue, enqueue_tx, outbox_enqueue_tx).

Job

A job row, as returned by get_job and carried inside a claim’s boxed JobHandle (job(&self) -> &Job).

QueueOpts

Queue-level option stamps (ADR-010 §3/§3a).

Schedule

The schedule() read-back value (upsert by name).

ScheduleOpts

Options for schedule() — types identical to their EnqueueOpts twins (no delay/run-at fields: boundary fires are ready at fire time, ADR-009 §3).

StopToken

A cloneable cancel handle for run_schedules(stop).

StreamEvent

A stream event — honker’s shape with one rename (topic → stream, ADR-015 §3).

Wake

A wake: the one piece of semantic content the wake contract allows — the channel name. No payload is surfaced (honker’s Notification { id, channel, payload } is not); consumers needing content use streams (the guarantee split, ADR-006). Wakes are hints: their multiplicity is not part of the contract (coalescing on SQLite, per-notify on Postgres).

Enums

Error

The crate’s error taxonomy (ADR-008 §5): a small closed set of contract-meaningful variants plus the opaque Error::Database fallback. Nothing engine-specific ever rides the surface; driver detail lives in the source chain of the opaque variant.

JobState

A job’s lifecycle state. Dead-letter is a move to dead storage (ADR-010 §4); get_job sees dead rows with last_error/died_at.

NameKind

Which namespace class a name belongs to (ADR-008 §4).

Constants

RESERVED_LISTENER_RECONNECTED

The one v1-reserved string (ADR-008 §4): the Postgres engine’s synthetic reconnect-wake channel, delivered as Wake { channel: RESERVED_LISTENER_RECONNECTED } on every subscriber’s receiver after a watcher reconnect. Public in core so the pg engine and the contract suite reference the same constant.

RESERVED_PREFIX

The reserved namespace prefix (ADR-008 §4). Engine-derived names in consumer namespaces (e.g. an outbox’s backing queue) carry it; consumer-supplied shared-namespace names carrying it are rejected with Error::ReservedName.

Traits

Delivery

The delivery callable Outbox::run_once takes.

EventReceiver

The durable stream subscription handle StreamHandle::subscribe returns.

JobHandle

The claim handle: the row value plus its ops.

Lock

A held named lock.

Outbox

The outbox-scoped handle for one outbox name.

Queue

The queue-scoped handle: enqueue, claims, and maintenance ops for one queue name.

Store

The store handle: one object, every mechanism behind it.

StreamHandle

The stream-scoped handle: publish, cursor reads, offsets, trim, and the durable subscription.

TxHandle

The caller-held transaction handle.

WakeReceiver

The wake receiver: the durable-subscription-free listen side of the notify mechanism.

Functions

encode_payload

Serialize a trait-crossing payload Value to the stored byte form.

payload_as

Decode stored payload bytes into a concrete target type.

validate_local_name

Validate a consumer-local identifier (stream-consumer names, owner on try_lock, worker_id on claims): non-empty only.

validate_name

Validate a name per its NameKind.

validate_shared_name

Validate a shared-namespace name (channels, streams, queues, outboxes, locks, schedule names).

Type Aliases

BoxedFuture

The future type every async contract method returns.

Result

The crate’s result type — every fallible operation in the contract surface returns this. Ok never carries a “null” sentinel: no-work claims and unlanded job/lock ops are values, not errors (ADR-008 §5).

WithTxClosure

The pinned closure shape with_tx takes (ADR-007): a FnOnce(&mut dyn TxHandle) -> BoxedFuture<Result<()>> — dyn-encoded for object safety, Send because the transaction’s future must be.