# API Stability
`ic-sqlite-vfs` starts at `0.1.0`.
## Stability Contract
The project has not promised compatibility for deployed canisters yet.
For all `0.x` releases, breaking changes may include:
- stable memory superblock fields
- DB image region layout
- `Db` facade signatures
- migration API
- import/export API
- checksum meaning and algorithm
- compile-time SQLite flags
Patch releases should remain bug-fix only when practical. Production users
should still pin exact versions.
## Upgrade Contract
Canister upgrades are tested for the same crate version.
Cross-version upgrade compatibility is not guaranteed in `0.x`. If a release
changes the stable layout, migrate with export/import:
1. deploy the old version
2. run `db_integrity_check`
3. export the full DB image with `db_export_chunk`
4. deploy the new version to a fresh canister or controlled upgrade path
5. import with `db_begin_import`, `db_import_chunk`, `db_finish_import`
6. run `db_integrity_check`
## Current Layout
`0.1.0` uses:
```text
offset 0..64KiB superblock
offset 64KiB.. active and inactive SQLite database images
```
The superblock stores the active DB image offset and logical size. The SQLite
database image itself is portable through the chunked export API.
In `0.1.0`, `checksum` is last verified checksum metadata. It is not a
durability boundary. Update commits use a heap write overlay, publish a new
active DB image through the superblock, advance `last_tx_id`, and may set
`checksum_stale`. `db_refresh_checksum` and `db_refresh_checksum_chunk` are the
only operations that persistently update the stored checksum after a normal
commit.
## Road To Stable
The `1.0` line requires:
- frozen superblock format
- documented migration path for layout changes
- stable `Db` facade
- stable import/export checksum format
- build setup that does not require copying repository support files