I/O Pimdir

pimdir store for Rust: a SQLite and content-addressed blob storage backend for io-replica

This library is composed of 2 feature-gated layers:

• Low-level I/O-free core: no_std-compatible schema, statements and model-to-column encodings, reusable by any implementation
• Mid-level std client: PimdirStore, which runs the statements against SQLite and the blob files, servicing the io-replica storage seam

Table of contents

• Features
• Specification
• Usage
• Examples
• AI disclosure
• License
• Social
• Contributing
• Sponsoring

Features

• Portable store: a single SQLite index plus a content-addressed blob directory, readable by any conformant pimdir implementation.
• Deduplicated bodies: each body is stored once by content hash, so a message filed in two mailboxes costs one copy.
• Offline-first: keeps the shared item and a per-source base, the raw material a sync engine reconciles against.
• Short public ids: one small, store-global id per message, shared across every collection and never reused.
• Crash-safe writes: one transaction per batch, bodies durable before the rows that reference them, and blobs garbage collected inside it.
• Action queue: processes that do not own the store request mutations by appending actions the owner applies exactly once, with parked failures queryable and collection generations carrying the handle-space epoch to readers.
• no_std core: the schema, statements and encodings need no allocator beyond alloc and pull SQLite in only behind the client feature.

Specification

io-pimdir implements the pimdir on-disk store specification: a SQLite database plus a content-addressed blob directory, with a canonical schema and forward-only migrations. The spec is the cross-implementation contract, so a store written here is readable by any other conformant implementation (a native Android SQLite store, for example). The sync model it services (a shared item, a per-source base, detail levels, conflicts) lives in io-replica.

Usage

The whole API is documented on docs.rs.

Examples

The tests demonstrate real usage: opening a store, servicing the storage seam, and the round-trip through SQLite and the blob directory.

AI disclosure

This project is developed with AI assistance. This section documents how, so users and downstream packagers can make informed decisions.

• Tools: Claude Code (Anthropic), invoked locally with a persistent project-scoped memory and a small set of repo-specific rules.
• Used for: Refactors, mechanical multi-file edits, boilerplate (feature gates, error enums, derive macros, trait impls), test scaffolding, doc polish, exploratory design conversations.
• Not used for: Engineering, critical code, git manipulation (commit, merge, rebase…), real-world tests.
• Verification: Every AI-assisted change is read, compiled, tested, and formatted before commit. Behavioural correctness is verified against the relevant spec, not assumed from the model output. Tests are never adjusted to fit AI-generated code; the code is adjusted to fit correct behaviour.
• Limitations: AI models occasionally produce code that compiles and passes tests but is subtly wrong. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.
• Last reviewed: 02/08/2026

License

This project is dual-licensed under the MIT and Apache-2.0 licenses.

Social

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Contributing

Contributions are welcome: start with CONTRIBUTING.md, which opens with the Pimalaya-wide guides to read first.

Sponsoring

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022 → 2023: NGI Assure
• 2023 → 2024: NGI Zero Entrust
• 2024 → 2026: NGI Zero Core
• 2027 in preparation…

If you appreciate the project, feel free to donate using one of the following providers: