Upgrading to 0.6.20
2026-11-10. A superseded version now keeps serving the channels only it declares, until it retires, where 0.6.18 and 0.6.19 drained it whole. Another owner is refused such an endpoint until then. A literal local:// send to another package, or to another version of the same package, is refused at lint and deploy. The engine uses about half the CPU it did under load: evaluation no longer copies the variables, and jemalloc is the allocator. Coverage can be checked against requirements, in named compliance cycles. RabbitMQ and AMQP broker credentials accept secret: references. Two additive migrations run at boot: V1003 (deployments) and V904 (coverage, at the store’s next first use). There is no archive format, deploymentId or snapshot format change.
Before you upgrade
Check these against what you run:
- A
q:sendto a literallocal://address that is not one of the package’s owntransport: localchannels. Another package, another version of this package, and a barelocal://<name>are now refused bysutra lint,sutra packageand every deploy path, withSUTRA.CONFIG.SEND.LOCAL_DESTINATION_CROSSES_PACKAGE. A destination containing${is not judged. A storeddbdeployment with such a send keeps running and logs the error at each load. A file in a deployments folder with one goesFailedat the next scan, including the first boot after the upgrade. Replace the send with an outbound channel the other package listens on. - A
calledElement, or a<q:dispatch>case or default, that names no process of the package is refused the same way, withSUTRA.CONFIG.CALL_ACTIVITY.UNKNOWN_CALLED_ELEMENT, with the same exemption for stored rows and the same effect on a folder. AcalledElementthat a<q:dispatch>replaces is never used, so it is not checked. - An old version can now hold an endpoint for as long as it has running instances. If you move an endpoint from one module to another (another owner) while the old module’s previous version is draining, the deploy is refused until that version retires. A version with instances parked indefinitely holds its channels indefinitely.
/sutra/deploymentsshows the count underdrainingInstances. - New traffic can start on the old version after the flip, on the channels it keeps. Moving that traffic to the new version is up to your integration.
- New warnings.
SUTRA.CONFIG.PROPERTY.BLANK_REFERENCE,SUTRA.DEPLOY.ENDPOINT.CHANNEL_CHANGED,SUTRA.DEPLOY.ENDPOINT.START_ON_WAITand the lint warningSUTRA.CONFIG.CHANNEL.START_AND_WAITare described below. None of them refuses anything.
Upgrading a deployment in place
When a new version of a tenant and module takes over, the old version drains as before: it takes no new work on the channels the new version has, and its running instances finish on it. New in 0.6.20, an inbound channel that no newer version declares, by name or on any of its endpoints, stays served by the old version, starts included, until the old version retires at zero running instances and zero pending outbox. SUTRA.DEPLOY.ENDPOINT.SUPERSEDED names those endpoints, and the timer starts that stop at the drain:
[WARN] SUTRA.DEPLOY.ENDPOINT.SUPERSEDED — deployment acme--orders--2.0.0 takes over from acme--orders--1.0.0, an earlier deployment of the same tenant and module. acme--orders--1.0.0 drains: it takes no new work, and its running instances finish on it. Channels only it declares stay served by it until it retires: POST /orders/release, POST /orders/legacy.
- What the old version keeps is recomputed at every change. Undeploying the new version gives the old one back every channel it declares, the ones it shared with the new version included, until it retires; then they stop. Undeploying the old version itself, while it is active, stops them.
- Retirement is rechecked. A version that just retired is checked again until it is quiet twice; one that had work arrive after all goes back to draining.
- A version that keeps feeding itself over its own channel never retires. The engine does not stop it.
GET /sutra/deploymentsnow shows each draining version’s running instances underdrainingInstances({"<deploymentId>": n}), andGET /sutra/deployments/{id}gainsinstancesfor a draining version. Thedrainingarray is unchanged. - Versions already draining when you upgrade the engine stop serving as before. Only a version superseded on 0.6.20 keeps channels.
- In a deployments folder, removing the old version’s file stops its channels, and the answer survives a restart.
Another owner is refused an endpoint a draining version keeps, until it retires:
[SUTRA.DEPLOY.ENDPOINT.COLLISION] http endpoint 'POST /orders/release' stays with draining deployment acme--orders--1.0.0 (2 running instances) until it retires
0.6.19 let another owner take it at once. POST /admin/deployments/check gives the same answer.
Upgrade warnings. These name what changes and how many instances are parked on it, and never print an auth value:
SUTRA.DEPLOY.ENDPOINT.CHANNEL_CHANGED: the deploy changes a channel an older version has instances parked on: its inbound auth, codec, schema, address or transport, or “renamed or replaced” when its endpoint is now served under another channel name.SUTRA.DEPLOY.ENDPOINT.START_ON_WAIT: a new start event listens where the older version waits. Start events are tried first, so a reply meant for a parked instance starts a new one.SUTRA.CONFIG.CHANNEL.START_AND_WAIT:sutra lintwarns about the same shape within one package.
Unchanged: a resume on a channel the new version changed is processed with the new version’s binding; an old instance parked on a channel the new version serves under another name is still unreachable from it (now warned); a retry across a version flip still runs again.
Schema: migration V1003 adds deployment_archive.retains_channels on PostgreSQL, MySQL and SQL Server. It is FALSE for rows drained before it existed.
The walkthrough is Upgrading a deployment in place; One endpoint, one deployment describes how the other deployment paths behave.
Less engine CPU under load
- Expressions evaluate without copying the variables. A FEEL dotted path walks nested values by reference and copies only the value it ends on. Data tasks, exclusive gateways and
q:paraminputs evaluate against the live variables, and each operation still sees the previous one’s result. A strict template engine gets a render model built without null entries in one pass, with the same JSON and key order. - jemalloc is the engine’s allocator. It is a default feature,
jemalloc, ofsutra-dist, and is never linked on MSVC targets. A build with--no-default-featuresdrops it, along with the other defaults, and uses the system allocator. jemalloc fixes its page size when it is built: an arm64 image build setsJEMALLOC_SYS_WITH_LG_PAGE=16(64 KiB), so the binary also runs on kernels with 16 or 64 KiB pages. If you build your own arm64 binary, set it too, or the binary aborts at start on such a kernel. amd64 is unaffected. - Measured on a laptop at 200 messages/s for 60 s, every message completed, none duplicated: steady engine CPU fell from about 316% to about 139% of one core, roughly 42% from the evaluation change and a further 24% from jemalloc. With database writes off, 267% to 121%. jemalloc used less CPU than mimalloc and had the lower p99. The runs were bound by the laptop’s disk, so their latencies are only indicative; the CPU figures are the reliable ones. A relay benchmark at 500 messages/s showed no change.
Coverage against requirements, in compliance cycles
The walkthrough is in Coverage.
- A requirements map. A package can ship
coverage/requirements-map.yaml, mapping each declared path to requirement ids, a weight (default 1, above zero) and the test cases that walk it.sutra coverage checkthen adds acomplianceobject: per-requirement and weighted percentages, uncovered paths with their cases, the cases to run, and paths with no cases or no mapping.--thresholdgates the weighted percentage. Every declared path counts; there is no way to exclude one. A package with no map reports as before. Lint:SUTRA.CONFIG.COVERAGE.MAPPING_ROUTE_UNKNOWN(error, a key that matches no declared path) andSUTRA.CONFIG.COVERAGE.MAPPING_ROUTE_UNMAPPED(warning, a declared path the map leaves out, counted at weight 1). - Cycles.
sutra coverage cycle declare|activate|deactivate <LABEL>andsutra coverage cycle list, plus--cycleoncoverage checkandcoverage reset. While a cycle is active, every mark for that deployment records to it, including thecoverage:reportandcoverage:resetoperations. A mark belongs to the cycle active when its instance completes. One cycle can be active per deployment: a second activation is refused (SUTRA.RUNTIME.COVERAGE.CYCLE_ALREADY_ACTIVE), as is activating an undeclared label (CYCLE_UNDECLARED); reactivating a cycle continues it. With none active, coverage records as before, andcheckandresetwithout--cycleread the marks recorded outside any cycle. Cycles belong to a deployment id, so a changed package starts with none. Thesutra.coverage.percentgauge and the path counter are not cycle-aware. - To re-run a case, send
<cycle>:<case>:<attempt>as the idempotency key on a channel that declaresidempotency-key-header: a repeat of an attempt does nothing, the next attempt runs. - Schema: V904 adds four coverage tables (
coverage_cycle,coverage_active_cycle,coverage_cycle_metric,coverage_cycle_fragment) on PostgreSQL, MySQL/MariaDB and SQL Server. Existing rows are untouched and read as “no cycle”.
Connection references
See References in connection properties.
- RabbitMQ and AMQP broker credentials accept
secret:KEYand${secret:KEY}.usernameandpasswordnow take exactly the whole-value forms the reference resolver resolves, plusk8s:secret/<name>#<key>. 0.6.19 refused the twosecret:forms there. A literal, or text with a reference inside it such aspre${X}, is still refused withSUTRA.STARTUP.REFUSED.HARDCODED_SECRET. - RabbitMQ now accepts a lowercase
${name}in credentials, as AMQP already did. It used to refuse it. - A reference that resolves to blank now warns
SUTRA.CONFIG.PROPERTY.BLANK_REFERENCE, naming the channel, the property and the reference as written, never a value. 0.6.19 applied the transport’s default silently: RabbitMQhostbecamelocalhost, Kafkagroup.idbecamesutra-<channel>. That still happens, and a blank required property is still refused, now after the warning. The explicit-empty forms${NAME:}and${secret:KEY:}do not warn, so write an optional setting that way. This covers the connection properties ofkafka,rabbitmq,amqp,gcp-pubsub,fileandaws-sqs, not credentials or data-store URLs.
Delivery and data stores
- Each failed delivery attempt that will be retried now logs a WARN with the destination, the cause’s code and message, the attempt number and
next_attempt_at. Before, a retried attempt logged nothing, so a callback that arrived seconds late gave no cause. - A closed in-process hand-off no longer delays delivery by 30 seconds. Outbox rows are inserted due after a short grace for the in-process hand-off. When the hand-off had closed before the commit, its rows waited out that grace. Now exactly those rows are made due at once, if they are still as inserted (never a leased, deferred or poisoned row), and the dispatcher is woken, so the next poll tick delivers them. Delivery stays at-least-once with the same dedup.
- A coded data-store refusal keeps its code. An edited migration that was already applied refuses the store with
SUTRA.RUNTIME.DATASTORE.MIGRATION_CHECKSUM, but the step failed withSUTRA.RUNTIME.UNEXPECTED, so the dead letter’scause_codeand its log line never showed the cause. It now fails with the store’s code and logs at ERROR, naming the store and the script, never the key. Routing is unchanged: a non-idempotent flow is still dead-lettered, an idempotent one requeued.
Fixed in the documentation
sutra.outbox.retry.base-delaydefaults toPT1S, as the code always had it; the configuration guide saidPT5S.- The 0.6.18 notes said a dropped delivery’s audit record has an empty
instance_id. No instance owns it, so it is NULL: select it withinstance_id IS NULL.
Tooling
- Load steps report resources.
tools/sutra-load-testrun.shandrelay-bench.shnow report engine CPU and RSS and PostgreSQL CPU, IOPS (pg_stat_io) and WAL volume for each step, fromstep-metrics.sh, as a table and a.metrics.json. A metric it can’t read printsunavailable, never 0.
Security
- RUSTSEC-2026-0459 is ignored in
cargo audit, time-boxed. It is inlibsqlite3-sys0.30.1, which is inCargo.lockonly becausesqlxdeclares its optional SQLite driver through a weak feature. No crate enables SQLite, so it is compiled into nothing:cargo tree -i libsqlite3-sys -e all --target allis empty, andcargo deny, which resolves the real graph, does not see it. Nosqlxrelease allows the fixed 0.39 yet. The ignore is dropped when one does.
For extension authors
sutra_envref_spi::is_whole_reference(whether a value is exactly one whole reference form) andis_explicit_empty_defaultare new.StoreError::with_codeandStoreError::codeare new insutra-executor; a store adapter that keeps a refusal’s code passes it through them.OutboxSignal::hand_offinsutra-channelsnow returns the ids it could not hand off.sutra-channelsgainswait_subscriptionsandmessage_types_can_overlap.