Search all skrzynka documentation

Version authority#

Cargo.toml is the only source of the Skrzynka version. skrzynka version reports that value. Versions follow Semantic Versioning with the Product Guidelines 0.x rule: a breaking change advances the minor slot; additive and corrective changes advance the patch slot until the public contract is deliberately declared stable at 1.0.0.

Public contract includes CLI commands and machine JSON, authenticated /v1 HTTP resources, organization isolation, the mailbox profile, SQLite schema semantics, loopback-only operation, integration capability declarations, and documented reply and outbound idempotency behavior.

Channels#

Channel	Audience	Coordinate	Guarantee
Development	Contributors and controlled local evaluation	Exact source commit	Shared qualification of exact committed source; no automatic upgrade
Stable	Not yet open	None	No stable artifact is currently published

main is moving development source, not a release coordinate. .wisent-release.json declares candidate-only Stado artifacts for darwin-arm64 and linux-amd64; it does not open Stable or install a service. After committing and pushing, use stado release changes submit --source <checkout> --commit <full-sha> --task <task-id> --session <session-id> --json, then stado release changes list --task <task-id> --json. An accepted queued handoff is not a build, deployment or successful mail import. release/build.sh preserves the builder-owned CARGO_TARGET_DIR, checks the built CLI version and stages bin/skrzynka, the Cargo build record and relative SHA-256 digests under WISENT_OUTPUT_DIR. Stado owns immutable publication and provenance; existing version bytes must not be replaced. Native application and graphical qualification remain separate requirements.

The separate skrzynka-desktop checkout declares a candidate-only darwin-arm64 producer with the same source handoff. Its archive build requires Stado 0.22.0 or later. Before packaging, stado product swift --json test --test-product SkrzynkaDesktopPackageTests --filter GmailConnectionTests.testTheRealReportDecodesIntoEveryPathTheScreenRenders --xunit-output .build/gmail-connection-tests.xml runs the native decoder against the real skrzynka executable and an isolated missing-vault refusal. SKRZYNKA_BIN may select that executable; an absent executable fails rather than skips. Commands and the real report remain under .build/test-results/. This is a refusal-contract check, not successful Gmail authentication or mail receipt.

The native release/build.sh consumes the builder's WISENT_SOURCE_DIR, WISENT_OUTPUT_DIR, WISENT_PLATFORM, WISENT_VERSION and WISENT_SOURCE_COMMIT. It requires noninteractive signing through an explicit Skarbiec certificate item, a provisioned keychain, or certificate and private-key PEM inputs. It disables installation and restart, verifies the bundle's version and source revision, and stages Skrzynka.app, the build log, native reports, test XML and executable digest. A compiler or signing refusal leaves qualification failed. The real mailbox lifecycle and the dedicated-host graphical journey remain separate requirements; neither a queued handoff nor this candidate declaration opens Stable.

Compatibility#

API major version is the /v1 path segment. Every /v1 route except the provider callback requires a Wisent bearer and selected organization header; /healthz remains unauthenticated.
Database schema is recorded with SQLite PRAGMA user_version; this release owns schema 4.
The schema 1 to 2 migration assigns existing resources to the explicit legacy-local CLI namespace because no prior row contains a defensible Wisent organization identity. Schema 2 to 3 adds the outbound_messages table. Schema 3 to 4 executes ALTER TABLE mailboxes ADD COLUMN smtp_skarbiec_item_id TEXT; existing mailboxes, messages, replies, and outbound messages are not rebuilt or rewritten.
Same-minor 0.x builds must read the existing schema or refuse startup with an actionable migration error.
A client must ignore additive JSON fields and must not assume enum values beyond those documented.
IMAP support is IMAP4rev1 with direct TLS. SMTP support is required STARTTLS or implicit TLS.

Upgrade#

Stop every Skrzynka process sharing the database, back up the database and its -wal/-shm companions if present, build or install the exact target release, then start one process. Startup applies only migrations explicitly owned by that release. Credentials require no migration because only Skarbiec references are stored.

Rollback and recovery#

A code rollback is safe while the database remains on a schema understood by the older version. If a release advances the schema incompatibly, restore the pre-upgrade database backup before starting the older binary. Never run two versions against one database during rollback.

Reply attempts and outbound messages found in sending after an unclean stop become uncertain — stored as REPLY_UNCERTAIN and OUTBOUND_UNCERTAIN respectively, both with send was interrupted before terminal SMTP evidence was recorded. Skrzynka does not resend them automatically because SMTP may already have accepted the message. The operator inspects provider Sent mail, then creates a new attempt under a new idempotency key only when another send is appropriate.

A database restore recovers local mailbox references, normalized messages, reply attempts, and outbound messages, including their full plain-text bodies and delivery evidence. It cannot recover a revoked Skarbiec item or provider mailbox. Reconnect those authorities independently and run synchronization; IMAP UID deduplication prevents duplicate local rows for the retained mailbox record.

Release notes#

Every published release must state added, changed, corrected, removed, and security-relevant behavior; configuration and schema changes; compatibility; operator actions; rollback limits; and known limitations. The release record names the exact examples from the same source revision.