# v0.18.0 — Z-Set Delta Engine and Production Safety Hardening

> **Full technical details:** [v0.18.0.md-full.md](v0.18.0.md-full.md)

**Status: ✅ Released** | **Scope: Large** (~5 weeks)

> A mathematically rigorous multi-source delta computation engine, enforced
> cross-source snapshot consistency, and a systematic sweep eliminating
> unsafe code patterns from the entire codebase.

---

## What problem does this solve?

The differential engine's internal representation of changes was extended to
handle the general case of multiple source tables consistently. Cross-source
consistency checking (introduced in v0.4.0) was advisory — it could be
bypassed. And a code audit revealed a significant number of internal "panic"
calls that could crash the PostgreSQL backend process if triggered.

---

## Z-Set Multi-Source Delta Engine

The differential engine internally represents row changes as **Z-sets** —
multisets where rows can have positive weight (added) or negative weight
(removed). This mathematical framework, from differential dataflow theory,
allows the engine to correctly compose deltas from multiple source tables.

v0.18.0 rebuilds the core delta computation on a rigorous Z-set foundation
for joins across multiple source tables. This ensures that complex queries
involving joins between three or more source tables, where changes occur in
multiple sources simultaneously, always produce mathematically correct results.

*In plain terms:* the engine now has a solid mathematical foundation for
computing the exact right answer when multiple source tables change at the
same time — a situation that becomes increasingly common as stream tables
grow in complexity.

---

## Cross-Source Snapshot Consistency Enforcement

Previously, a stream table that joins multiple source tables would warn about
potential consistency issues but proceed anyway if the sources were not snapped
at the same transaction boundary. v0.18.0 makes this enforcement strict:
a refresh that would produce a snapshot that never existed in the actual
database is blocked, and the refresh is retried with proper locking.

*In plain terms:* you can no longer get a stream table that shows an "orders
joined to customers" result that combines data from different points in time —
the engine guarantees the result reflects a moment that actually existed.

---

## Production `.unwrap()` Elimination

In Rust, calling `.unwrap()` on a value that turns out to be absent causes
an immediate crash ("panic") of the process handling the request. In
PostgreSQL, that means the backend handling your query crashes and the
connection is terminated.

A systematic audit of all pg_trickle source code identified every `.unwrap()`
call that could be reached during normal operation. All were converted to
proper error handling: if a value is absent, a descriptive error is returned
to the caller rather than crashing.

---

## Unsafe Block Reduction

Rust's `unsafe` blocks allow operations that bypass the language's safety
guarantees — necessary when interacting with PostgreSQL's C internals, but
potentially dangerous if misused. The number of `unsafe` blocks in the
codebase was reduced by approximately 40% through the introduction of safe
wrapper abstractions.

Every remaining `unsafe` block has a documented safety justification.

---

## Scope

v0.18.0 is primarily a correctness and safety release. The Z-set delta engine
and consistency enforcement ensure correct results for complex multi-source
queries. The `.unwrap()` elimination and unsafe reduction make the extension
more robust in production, reducing the risk of backend crashes from
unexpected edge cases.
