che-orm 0.4.0

Typed SQLite and PostgreSQL ORM for che-rest applications
Documentation
# Release procedure

## Release versions

Current workspace package versions:

| Package | Version |
| --- | --- |
| che-orm-macros | 0.3.2 |
| che-orm | 0.4.0 (unpublished candidate) |
| che-sync-protocol | 0.1.0 |
| che-sync | 0.2.0 (unpublished candidate) |

Registry audit on 2026-11-12 confirms published core 0.3.3, macros 0.3.2,
protocol 0.1.0, sync 0.1.3 and REST 0.3.4, all non-yanked; che-tauri has no
registry entry. See [the registry audit](registry-audit-2026-11-12.json).
Completed preparation checks and remaining gates are recorded in the
[2026-11-14 verification report](release-verification-2026-11-14.md).
The new candidates require Rust 1.89, including the patched bundled SQLite driver.
The new candidates are core 0.4.0, sync 0.2.0 and REST 0.4.0. Bound queries and
SQLite datetime storage are breaking changes; bump minor versions under 0.x.
Macros/protocol source and original manifests match their published archives:
keep their versions and do not republish them. che-tauri's unused 0.1.1 candidate
can remain unchanged while its dependencies move to this new core/sync line.

Core 0.3.3 adds capture of ordinary-parent referential actions for model journals
and integer foreign-key support. Sync 0.1.2 also includes self-referencing UUID
models, initial-pull/pending-entity inspection and a feature guard for its
SQLite-only foreign-key test. Macros and protocol versions are unchanged.
Registry check on 2026-11-06 confirmed core 0.3.3, macros 0.3.2, protocol
0.1.0, sync 0.1.2 and REST 0.3.3 are already published and not yanked.
Do not republish those versions or move their tags. The former sync 0.1.3 and
REST 0.3.4 candidates have since been published; they cannot identify this source.
The initial-publication notes below describe previous candidates.

`che-orm-examples` is private (`publish = false`). Package the four public
crates explicitly rather than using `cargo package --workspace`.

## Historical candidate notes

The following notes record earlier release preparations, not the current
publication plan. Do not run their publication commands for this candidate.
Use [Publication](#publication) and the [release checklist](release-checklist.md)
for the current coordinated release.

### Candidate verification (2026-11-02)

- Workspace SQLite tests and documentation passed, including self-referencing
  UUID models and ordinary integer-parent foreign-key actions.
- All-target PostgreSQL compilation passed on Rust 1.88 after gating the
  SQLite-only external foreign-key fixture.
- Six sibling archives (the four ORM/sync packages, che-rest 0.3.3 and
  che-tauri 0.1.2) packaged together. Extracted ORM/REST/sync sources passed
  Rust 1.88 checks for SQLite/HTTP and PostgreSQL; extracted che-tauri passed
  all-target sync checks on the current stable toolchain.
- Native Tacit and the two-client Todo HTTP integration tests passed. Live
  PostgreSQL integration tests were not run without a configured test server.
- The new candidates have not been published to crates.io. Publish dependencies
  first, then repeat each ordinary registry dry run after indexing.

The 0.3.2 patch releases core and macros together. It adds app-prefixed table-name
inference from literals or shared constants, and updates the template with
`createapp`, single/modular layouts and explicit migration generation.
The template requires the published core 0.3.2. Sync package versions remain
0.1.0 for their initial publication; they have not previously been published.

### Initial sync publication: 0.1.0 (historical)

`che-sync-protocol` is transport/backend independent. `che-sync` depends on
`che-sync-protocol 0.1.0` and `che-orm 0.3.2`. Both require Rust 1.88.
Each sync archive includes its own README, changelog and MIT license. Review the
package file lists and preserve existing uncommitted application/example work
when preparing a release commit.

The remaining publication order is:

1. `che-sync-protocol 0.1.0`.
2. Wait for its crates.io index entry, then `che-sync 0.1.0`.
3. The downstream `che-rest 0.3.1` can then pass its normal registry dry run.

Before publication, validate both unpublished packages together using Cargo's
temporary package registry:

```bash
cargo publish --dry-run -p che-sync-protocol --allow-dirty
cargo package -p che-sync-protocol -p che-sync --allow-dirty
```

An ordinary `cargo publish --dry-run -p che-sync` cannot resolve the unpublished
protocol dependency. After protocol publication, repeat it without substituting
local dependencies. The joint package check is not a registry publication.

For extracted-archive Rust 1.88 verification, use the sibling REST helper:

```bash
TMPDIR=/tmp/opencode python3 ../che-rest/scripts/verify_sync_packages.py \
  --output /absolute/path/outside/source/repos/sync-0.1.0-verification
```

The output directory must be new and have room for five crates and their build
artifacts. It retains logs, archives and a SHA-256 report. The helper checks both
SQLite/HTTP and PostgreSQL against extracted sources; it requires cached optional
dependencies for its offline checks.

Publish only after reviewing and committing the intended release files:

```bash
cargo publish -p che-sync-protocol
# Wait for the protocol package to be indexed.
cargo publish --dry-run -p che-sync
cargo publish -p che-sync
```

Use distinct sync tags such as `che-sync-protocol-v0.1.0` and `che-sync-v0.1.0`
for this initial release; do not move the published core tag `v0.3.2`.

### Verified candidate (2026-10-27)

- Protocol `publish --dry-run --allow-dirty --locked`: passed.
- Joint sync packaging with `--allow-dirty --locked`: passed, using the published
  crates.io ORM 0.3.2 rather than a substituted ORM version.
- Sync tests, both backend builds, Clippy, API docs and both native examples:
  passed. Live PostgreSQL tests remain ignored without `TEST_POSTGRES_URL`.
- Extracted sync archives: Rust 1.88 all-target checks for SQLite and PostgreSQL,
  and SQLite protocol/engine tests passed against the published ORM.
- Audit findings were addressed in lock files: Tokio 1.54.1, ctutils 0.4.4, and
  matching downstream REST TLS dependencies. Current ORM/REST/fullstack lock files
  have no reported vulnerabilities. Auditing the sync archive lock cannot check
  registry yanked status for the as-yet unpublished protocol package; repeat
  the audit after it is indexed.

Final extracted-archive report and logs are retained at
`/home/che/web/rust/che-sync-010-final-2552aaa0/result.json`.

| Archive | SHA-256 |
| --- | --- |
| `che-sync-protocol-0.1.0.crate` | `cf3afbcad85d21683a4e4252af1589ad9ce19daf38126b55ef11769e14e1c8c8` |
| `che-sync-0.1.0.crate` | `452dff20c5b9dec6f9436d5d42dc1d7d320083e653168550eb3e69c85b809d19` |

These hashes identify the reviewed local candidates; packaging again after a
release commit can change VCS metadata and therefore the archive hashes.

The 0.3 ORM release introduces async database access with feature-selected
SQLite/PostgreSQL backends and role-aware synchronization. Shared models use
`#[orm(sync)]`, with `SchemaSet::client_model` or `server_model` selecting their
database role. Prefer [protocol-2 model journals](model-sync.md) for new clients;
their independent `pull`/`flush` methods have no snapshot phase. The
[scoped compatibility API](sync.md) retains explicit `full_load` and its own
history/upgrade rules. Both contracts require persistent server history;
replacement/history rewind is outside them.

## Verification

The `Release checks` workflow verifies SQLite, live PostgreSQL, Rust 1.89 and
the contents of the publishable archives. Run the equivalent checks locally
before tagging. SQLite and PostgreSQL are mutually exclusive features.

```bash
cargo fmt --check
cargo test --workspace --locked
cargo doc --workspace --no-deps --locked
cargo run -p che-orm-examples --bin manage --locked -- schema
cargo run -p che-sync --example offline --locked
python3 scripts/check-template.py
cargo +1.89.0 check --workspace --all-targets --locked
cargo +1.89.0 check -p che-orm -p che-sync --all-targets --locked --no-default-features --features postgres
cargo package -p che-orm-macros -p che-orm -p che-sync-protocol -p che-sync --locked
```

Set `TEST_POSTGRES_URL` to a disposable PostgreSQL database, then run the four
PostgreSQL commands in the workflow, including ignored runtime/model-role and
`model_log_postgres` tests. The latter verifies protocol-2 journals, concurrent
commits, no-op suppression, deferred FK projection and SET NULL.
For a local working tree review, packaging can use `--allow-dirty`; the release
must include the reviewed new source and test files in its commit.

Validate the matching downstream `che-rest` checkout with:

```bash
cargo test --test sync --test model_sync --test sync_lifecycle
cargo test --features sync-http
```

The matching che-tauri client and Todo application are separate downstream
workspaces. When changing sync contracts, also run their checks listed in the
[protocol-2 guide](model-sync.md#verification). Desktop compilation and the
two-client HTTP test do not replace manual GUI or deployment migration review.

For an existing installation, rehearse its compiled follow-up migration on a
copy of its database. Verify revisions, scope ownership, UUIDs, tombstones,
receipts, cursors and pending edits as described in [sync.md](sync.md) and the
[protocol-2 migration guidance](https://github.com/che4web/che-rest/blob/main/docs/model-sync.md#rehearsing-an-existing-installations-migration).
Fresh-database tests do not validate this application-specific upgrade.

## Publication

Publish only after separate explicit authorization, dependency-order verification
and review of application-owned SQLite upgrades. Current order is **che-orm
0.4.0**, **che-sync 0.2.0**, then downstream **che-rest 0.4.0**. Already published
versions/tags remain untouched. Review and commit the verified release first:

```bash
cargo publish --dry-run -p che-orm --locked
# Publish core only with separate approval; wait for indexing before sync dry run.
cargo publish --dry-run -p che-sync --locked
```

After core 0.4.0 and sync 0.2.0 are published and indexed, REST 0.4.0 can pass
its ordinary registry dry run. Verify registry/docs.rs before creating any new
tags. Keep `v0.3.3`, `che-sync-v0.1.3` and REST `v0.3.4` intact. che-tauri's
initial publication is a separate decision; Tacit 0.1.14 remains an application.

Packaging and dry runs are verification only, not authorization to publish.
See the [release checklist](release-checklist.md) for the publication gates.