Changelog

Detailed changelog: Flow Ledger, docs, and operational semantics

Release Scope

• Postgres Flow Ledger: workflow state, leases, operation idempotency, side-effect replay, and timeout due-row discovery are backed by PostgreSQL through QAIL AST commands.
• Workflow production semantics: docs now separate engine behavior from executor responsibilities such as provider idempotency, lease TTL sizing, and scheduler discipline.
• Side-effect identity: v2 side-effect operation ids include state generation so workflows that revisit the same state/step path do not collide with old completed work.
• Platform manual: docs now include a platform map, native access-policy semantics, tenant-first RLS boundaries, and workflow/Flow Ledger rollout guidance.
• Repository hygiene: stale root artifacts were removed, and the performance entry point now points to current benchmark docs and maintained observability assets.

Highlights

• PostgreSQL protocol hardening: backend control-frame validation, frontend send/flush handling, prepared statement lifecycle checks, and pooled raw cleanup now fail closed more consistently.
• Native AST/parser validation: grammar, schema/query-file parsing, native MERGE handling, identifiers, and expression encoding reject more malformed or unsafe AST shapes before PostgreSQL execution.
• MERGE live behavior: PostgreSQL coverage exercises complex expressions, CTE/query sources, RLS-scoped update/insert/delete flows, and invalid ASTs that must fail before mutation.
• Panic-safety gate: legacy COPY/time helper paths avoid runtime panics, and encoder FFI cleanup sites satisfy stricter unsafe documentation gates.
• Real database validation: PostgreSQL 18 lab coverage passed for cursor cleanup, set operations, recursive CTEs, access-checked execution, MERGE, legacy integration, and seeded RLS behavior.

Detailed changelog: native vertical policy and the audit pass behind v1.3.0

Highlights

• Native vertical access policy: qail_core::access adds deny-by-default policies, role/scope requirements, operation permissions, read/write/returning column rules, wildcard fallback, super-admin bypass, and TOML/JSON policy loading.
• Gateway policy integration: opt-in [access] config lets the gateway enforce native policy across REST CRUD, nested/expanded reads, RPC probes, QAIL text/binary/batch endpoints, transaction queries, and WebSocket/live-query paths.
• PostgreSQL statement cache safety: hot prepared statements now promote only after parse success, stale handles are evicted or reparsed, cached statements survive execute errors, prepared identity is aligned, and NOTIFY flushes drain before returning.
• Migration verification: composite foreign-key options survive parse/diff/apply, strict migrations support those options, state diff rejects composite foreign-key drift, and post-apply verification checks table constraints against the live database.
• Access-policy checks: MERGE source subqueries, transaction subqueries, invalid policy numerics, and value expressions that read existing row data now fail closed when policy access is missing.
• Gateway numeric safety: Qdrant JSON integer drift is rejected, oversized REST integers and precise numeric responses are preserved, branch replay integers compare exactly, and REST write tenant exemptions stay explicit.
• Runtime edge fixes: workflow transition guards, charge amount validation, branch cursor drift, null bind batch params, zero-parameter binds, Qdrant little-endian vector encoding, and SDK path-segment encoding are covered.
• Release validation: the release was checked with the Rust workspace test suite, Clippy, SDK tests, and live PostgreSQL lab coverage for strict migrations, MERGE, access checks, seeded RLS, and gateway native access policies.

Highlights

• RLS directives: pulled schema files may include table-level enable_rls and force_rls directives.
• PostgreSQL types: multi-word column types such as DOUBLE PRECISION and TIMESTAMP WITH TIME ZONE parse correctly.
• Comments: comment text containing quoted examples no longer breaks schema parsing.

Highlights

• Protocol safety: malformed backend ordering, bad stream frames, unexpected EOF, and corrupted protocol messages now mark affected connections as desynchronized instead of returning them to normal reuse.
• SQL boundary safety: NUL and UTF-8 handling now fails closed across savepoints, AST-native SQL buffers, gateway explain SQL, COPY text decoding, backend wire decoding, and URL percent-decoding.
• Live coverage: PostgreSQL 18 lab coverage was refreshed for MERGE, set operations, recursive CTEs, cursor cleanup, COPY callback recovery, LISTEN/NOTIFY payloads, savepoint rejection, and NUL query rejection.

Highlights

• Schema pull: generated columns, identity defaults, expression indexes, enum extensions, and composite foreign-key drift are handled in live introspection and shadow verification.
• Replay safety: migration risk and verification paths compare constraints, defaults, generated expressions, indexes, and extension dependencies against the real database state.
• Branch overlays: live PostgreSQL audit paths for merge, set-operation, recursive-CTE behavior, and bad overlay replay failure modes were restored.

Highlights

• Gateway mutation/event semantics: create, upsert, update, and delete paths now apply stricter tenant guards, policy filters, trigger behavior, cache invalidation, branch context, and conflict-update event classification.
• Workflow correctness: nested ForEach context preservation, wait-event resume validation, timeout fallback execution, and transition checkpointing/idempotency risks were fixed.
• Qdrant tenant safety: tenant-scoped vector upserts namespace point IDs, preserve the original caller-facing IDs in hidden payload metadata, and enforce tenant/policy boundaries before mutation.
• Branch overlays: branch reads apply overlay operations chronologically with policy filters and post-policy projection, while branch merges apply rows in global sequence order.
• Durable webhook outbox: gateway mutation triggers now persist webhook deliveries through an outbox path with bounded dispatch behavior and better old/new row payload preservation.
• Runtime surface: the supported stable runtime is centered on PostgreSQL and Qdrant; SQLite, DynamoDB, and MongoDB transpiler compatibility symbols remain available for 1.x consumers.

Highlights

• Connection Pool Hardening: Standard library synchronization mechanisms optimized for zero state leakage under highly concurrent tenant/RLS workloads.
• gRPC Connection State Machine: Monotonic connection generation tracking implemented in Qdrant transport driver to prevent reconnect storms.
• Webhook Scale & Boundaries: Semaphore-throttled webhook worker capacity increased to 512 with safe task execution timeouts.
• Overlay & RLS Rules: Upgraded recursive parser, structured policy injection, and indexed tenant database overlays.
• Workspace Parity: All 8 workspace crates (core, pg, qdrant, gateway, workflow, lsp, encoder, cli) fully promoted to v1.0.0.

Breaking Changes

• RLS builder API: the redundant try_with_rls() compatibility alias was removed; use with_rls(&ctx)?.
• Relation join API: the redundant try_join_on() alias was removed; use fallible join_on(...)?.
• Wire encoding: try_encode_cmd_binary() was removed; encode_cmd_binary() is the fallible binary encoder.
• Analyzer mode: unused AnalysisMode::Regex was removed; non-Rust files report TextSemantic.
• Build validation: the string-only validate_against_schema() wrapper was removed; use structured validate_against_schema_diagnostics().
• PostgreSQL cancel keys: legacy i32 cancel-key wrappers were removed; use bytes-native cancel key APIs.

Highlights

• Builder safety: RLS insert scoping now returns structured build errors for unsupported positional payloads instead of exposing a panic surface.
• Encoder safety: binary AST encoding now keeps payload-size failures on the fallible path.
• Tenant naming: docs and runtime guidance now consistently use tenant_id; legacy operator_id JWT claims are not mapped into tenant scope.
• Compatibility cleanup: old aliases and stale docs were removed ahead of the 0.28.x line.

Highlights

• Schema cache reload: LSP schema resolution is now workspace-scoped and reload-aware, preventing stale diagnostics and completions after schema edits.
• Completion gating: suggestions are constrained to active Rust builder and QAIL query contexts instead of appearing broadly in unrelated cursor locations.
• Diagnostics lifecycle: document versions are tracked, out-of-order changes are ignored, and closed documents clear diagnostics correctly.
• Range correctness: hover and embedded-query hit testing now use UTF-16-safe ranges for non-ASCII text.
• Versioning/docs: workspace crates and docs/install/readme references were bumped to 0.27.10.

Highlights

• Scanner inline comment handling: const column arrays with inline comments now parse correctly in scanner preprocessing without swallowing the remainder of the statement.
• Explicit apply parsing: parse_qail_to_commands_strict now accepts mixed command blocks (for example enum + alter + partial index) in explicit apply mode.
• Versioning/docs: workspace crates and install/readme references were bumped to 0.27.9.

Highlights

• Shadow DB handling: create/drop operations now quote shadow database identifiers so names like qail-engine-db_shadow work correctly.
• Versioning/docs: workspace crates and install/readme references were bumped to 0.27.8.

Highlights

• Gateway auth contract: platform scope now requires explicit platform_admin=true; legacy aliases are rejected.
• Migration scanner delta support: scanner now understands migration deltas and preserves helper-scoped tenant filters in an explicit AND cage.
• Driver docs positioning: qail-pg docs/examples were reframed around the driver-first native AST execution path.
• Versioning/docs: workspace crates and install/readme references were bumped to 0.27.7.

Highlights

• Versioning/docs: bumped workspace crate manifests and docs/install/readme references to 0.27.6.
• Release contract: this is a non-breaking patch release; runtime and API behavior are unchanged from 0.27.5.

Highlights

• Benchmark surface correction: the public Rust PostgreSQL benchmark now measures qail-rs from native Qail ASTs against pgx SQL strings instead of starting qail-rs from raw SQL.
• Aggregate fast path: grouped scalar aggregate results now use the dedicated four-column zero-copy receive path with tighter query/pipeline buffer reuse.
• Current benchmark read: the March 30 one-round native snapshot was a 15 / 15 throughput sweep; the latest April 22 median refresh is the live canonical read and stays positive on 14 / 15 throughput slices, all five p50 slices, and four of five p99 slices.
• Versioning/docs: workspace crates and docs references were bumped to 0.27.4.

Highlights

• Semantic parity: chained or_filter(...) behavior is now consistently preserved as grouped predicate intent (AND (... OR ...)) across runtime SQL generation paths.
• Regression coverage: parser/transpiler/encoder parity checks were extended to prevent future OR-to-AND behavior drift.
• Versioning/docs: workspace crates and docs references were bumped to 0.27.3.

Highlights

• Idempotency isolation: request fingerprints now include behavior-changing headers (prefer, x-transaction-id, x-branch-id, x-qail-result-format).
• Anonymous replay safety: unauthenticated requests now bypass idempotency caching to prevent cross-client key collisions when auth is disabled.
• Branch overlay correctness: update overlays now patch matching rows by PK, preserve PK identity for branch-only rows, and get-by-id can resolve branch-only overlays.
• Branch lifecycle hardening: overlay read/write/merge/stats SQL paths now operate only on active branches, branch create fails when parent is missing/inactive, and branch delete returns not found for non-active/non-existent branches.
• Auth gate ordering: branch read endpoints now enforce branch-admin authorization before DB execution.
• Versioning: workspace crates bumped to 0.27.2.

Highlights

• QWB2 strictness: binary endpoint now rejects legacy QWB1/raw-text payloads and uses strict QWB2 AST decode for ingress.
• Safety: binary AST decode now applies explicit payload limits to prevent unbounded allocation on malformed payloads.
• Gateway benchmark parity: release notes include text-vs-binary gateway benchmark validation under identical endpoint shape.
• Versioning: workspace crates bumped to 0.27.1.

Highlights

• Breaking API rename: standardized pipeline method names to pipeline_execute_* across driver/connection/pool surfaces (for example pipeline_batch -> pipeline_execute_count).
• Pipeline strategy: added AstPipelineMode (Auto, OneShot, Cached) plus plan surfaces AutoCountPlan and AutoCountPath.
• Prepared AST handle: added PreparedAstQuery with dedicated prepared AST execution APIs for repeat-query hot paths.
• Encoder fast path: added AstEncoder::encode_cmd_sql_reuse(...) for caller-buffer SQL/param reuse.
• Runtime hardening: cached AST pipeline now rolls back newly registered statements on encode/protocol failures and improves desync resilience.
• Policy behavior: gateway policy engine now denies when policies exist but none match table/operation, while preserving allow behavior for an empty policy set.
• Versioning: workspace crates bumped to 0.27.0.

Highlights

• Strict ordering: destructive/rename hints (drop*, rename) now execute before declarative create paths in strict migration compilation.
• Policy verification: migrate apply now validates policy state by final expected (table, policy) after all commands in a migration complete.
• Reliability: drop-and-recreate policy sequences in a single migration no longer fail from intermediate-state checks.
• Tests: added strict policy replace ordering coverage and final-intent expectation tests.
• Versioning: workspace crates bumped to 0.26.6.

Highlights

• Coverage: added forced QAIL_PG_IO_BACKEND=io_uring startup-path smoke tests.
• Tooling: added scripts/check-io-uring-linux-cross.sh for Linux cross-target validation with local zig fallback support.
• Runtime introspection: added PgConnection::transport_backend() for telemetry and verification.
• Feature wiring: removed stale tokio-uring coupling, added native-io-uring alias, and retained io_uring compatibility.
• Versioning: workspace crates bumped to 0.26.5.

Highlights

• Versioning: workspace crates bumped to 0.26.3.
• Docs/readmes: refreshed installation snippets and version references to 0.26.3.

Highlights

• Startup: default StartupMessage protocol is now 3.2 (196610).
• Compatibility: explicit protocol-version rejection triggers a one-shot retry using protocol 3.0 (196608).
• Wire decode: backend NegotiateProtocolVersion ('v') is now parsed and handled.
• Cancel path: cancel secret keys are now bytes-native (4..=256) with legacy i32 wrappers retained for compatibility.
• Hardening: integration tests now cover startup negotiation and downgrade boundaries.
• Versioning: workspace crates bumped to 0.26.2.

Highlights

• CI: fixed publish workflow breakage after tenant-only runtime cutover.
• Gateway: binary examples aligned to QWB1 wire format.
• Packaging: crate metadata/readme parity updates across release-track crates.
• Versioning: workspace crates bumped to 0.26.1.

Highlights

• Breaking: removed RlsContext::operator(...) and runtime operator-scoped aliases in favor of tenant-only constructors.
• Breaking: gateway runtime auth resolves tenant scope from tenant_id only; legacy operator_id claim no longer maps tenant context.
• Gateway: fixed policy evaluation to avoid premature deny when later matching allow policies exist.
• Gateway: expanded optimize_qail_for_execution(&mut cmd) coverage for consistent execution planning.
• Analyzer: reduced false positives from comment/string-literal noise and tightened semantic diagnostics.
• SDK/Docs: direct SDK support surfaced for TypeScript, Swift, and Kotlin; Node.js native binding remains deferred.
• Versioning: workspace crates bumped to 0.26.0.

Highlights

• CLI: added migrate down --force with non-TTY unsafe guard and wait-for-lock support.
• CLI: added JSON output mode for migrate analyze.
• Migrations: optional HMAC signing support for migration receipts.
• Migrations: advisory locks now scoped by database with stronger timeout diagnostics.
• Integrity: receipt signature verification enforced on apply and rollback paths.
• Versioning: workspace crates bumped to 0.25.1.

Breaking Changes

• qail-core: removed raw SQL helpers including Qail::raw_sql(...).
• qail-pg: removed direct raw-SQL APIs from the primary runtime contract in this release line (later versions may expose compatibility wrappers for legacy tests/examples).
• Encoder: AST runtime path no longer allows raw SQL pass-through.

Migration Guidance

• Use AST-native builders (Qail::get/add/set/del, typed filters, typed joins).
• Use session AST commands (Qail::session_set, session_reset) instead of raw strings.
• Legacy raw examples moved behind legacy-raw-examples and disabled by default.

Highlights

• PG auth: decode support for auth code 6 (AuthenticationSCMCredential) with explicit startup guidance.
• PG URL aliases: added krbsrvname, gsshostname, and gsslib compatibility mappings.
• Tests: added regressions for SCM auth decode and GSS URL alias parsing.

Notable Changes

• v0.24.5: docs domain moved to dev.qail.io, snippets/version references aligned.
• v0.24.4: standardized wording around SQL strings vs protocol bytes across docs.
• v0.24.2: added skip_locked support and user-scoped RlsContext::user(user_id).