Changelog

Copy Markdown View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.4.0 - 2026-08-03

Added

  • use AshReplicant.Checkpoint accepts an authorizers: option, so the generated checkpoint resource can carry Ash.Policy.Authorizer and enforce host-declared policies do blocks. The checkpoint is an internal watermark; a host that exposes its domain on a wire surface (JSON:API, MCP) previously had no way to lock the checkpoint down, because the macro emitted a resource with no authorizer and policies is not a declarable section without one. The sink still reads/upserts with authorize?: false on both paths (Sink.Impl.read_checkpoint/1, upsert_checkpoint/2), so effect-once is unaffected by whatever policies the host declares — including none, which fail-closes the resource to every actor except the sink. authorizers: defaults to [], identical to the option Ash already defaults to, so existing hosts get the byte-for-byte prior resource (no behaviour change). Verified against live logical-replication Postgres: checkpoint_policy_test.exs proves the authorizer + policies are present, a non-system actor is denied (hard Forbidden), a system actor is allowed, and the sink's authorize?: false path bypasses both.

0.3.3 - 2026-08-02

Fixed

  • Tenant reassignment on the SCD2 path no longer leaves a double-current version. The 0.3.2 relocate fix covered only the SCD1 (upsert) path. On the SCD2 (validity-windowed) path a tenant reassignment (same business key, new tenant) left the OLD-tenant version OPEN forever while opening a fresh current version under the NEW tenant — the entity read as "current" under BOTH tenants (a silent double-current split; a per-tenant open-uniq index permits it, so no error surfaced). Apply.Scd2 now terminally closes the old-tenant version on a resolved-tenant change (in addition to a business-key change), relocating the row. Regression test: scd2_apply_test.exs "tenant-reassigning update terminally closes the OLD-tenant version and opens under the NEW tenant".
  • Value-free preserved on the tenant-change check. The reassignment predicate was promoted to Resolver.tenant_changed?/2 and made scrub-safe: a raising tenant_mfa resolver is caught inside the check and reported as "not changed" (never propagating an unscrubbed row value out of the pre-apply tenant comparison, which sits outside the per-op scrub boundary). Both apply paths share the one helper.

Notes

  • Tenant-scoped mirrors REQUIRE REPLICA IDENTITY FULL on the source for reassignment detection: the check needs the old row's tenant, which is key-only under the default replica identity. Without RIF a genuine reassignment falls through to the pre-0.3.2 behavior (SCD1: the colliding upsert; SCD2: the double-current) — the same old_record dependency already documented for tenant-scoped deletes/PK-changes.
  • Reassignment detection also depends on a NON-RAISING tenant resolver. Resolver.tenant_changed?/2 treats a raising tenant_mfa as "not changed" (value-free), so an MFA that raises on old_record makes a reassignment invisible and the caller keeps its non-relocating path. tenant_attribute resolvers never raise; this affects only tenant_mfa and is not a regression (no path handled reassignment before 0.3.2/0.3.3).

0.3.2 - 2026-08-02

Fixed

  • Tenant reassignment no longer halts the mirror stream. When a source row's tenant attribute changed (same PK, new tenant_attribute value), a resource declaring a tenant-scoped upsert identity (identity :source_pk, [pk] under attribute multitenancy → a (tenant, pk) unique index) would fall through to an INSERT under the new tenant that collided with the row's GLOBAL primary key (the still-present old-tenant row). The upsert raised, the sink transaction rolled back, and the checkpoint froze — a fail-closed poison pill that stalled delivery for ALL tenants and retained source WAL indefinitely. Apply now treats a resolved-tenant change like a PK change: destroy the old-tenant row (resolved from old_record) then upsert under the new tenant, relocating the mirror row. Triggers only when both tenants resolve and differ, so non-multitenant resources and key-only old_record updates (no REPLICA IDENTITY FULL) are unchanged. Regression test: apply_test.exs "tenant-reassigning UPDATE … MOVES the row to the new tenant".

0.3.1 - 2026-08-02

Changed

  • Widen the replicant requirement from ~> 0.1.0 to ~> 0.3 so consumers can adopt the current replicant line (0.3.x) without a resolver conflict. ash_replicant calls only replicant's stable core (Replicant.{Change, SchemaChange, Sink, Transaction, lsn}, Replicant.start_link/1, Replicant.stop/1); verified compatible against replicant 0.3.1: mix compile --warnings-as-errors clean and mix test 90 passed / 0 failed (unit suite; the :integration gate — 52 tests needing a live wal_level=logical DB via ASH_REPLICANT_TEST_URL — is owed in CI before publish). No API or behavior change.

0.3.0 - 2026-07-14

Added

  • SCD2 history mirroring — a per-resource opt-in (history_strategy :scd2) that mirrors a source table into a host-defined validity-windowed version table (close-current + insert-version) instead of overwriting current state. Effect-once, fail-closed multitenancy, value-free boundaries, and Critical Rule 1 preserved; new ValidateHistory compile verifier; on_truncate :close. Audit-log needs remain served by AshPaperTrail on an SCD1 mirror.

Security

  • Multitenancy fail-closed at compile time — both tenant sources. ValidateMultitenancy now requires an Ash multitenancy block whenever a tenant_attribute or a tenant_mfa is declared. Without a block Ash silently ignores the tenant: option the sink passes, so every tenant's rows mirror unscoped into one table — a proven fail-open with no runtime error. The tenant_attribute arm shipped 2026-07-10; the symmetric tenant_mfa arm closes the parallel hole (2026-07-14). Any strategy (:attribute or :context), including a global? block, satisfies the gate. See ADR-0001.
  • A false-resolved tenant now fails closed. Resolver.resolve_tenant/2 rejected only nil/blank-string tenants; a tenant_attribute column holding boolean false or a tenant_mfa returning false resolved to {:ok, false}. Ash treats a falsy tenant as no scoping (neither force-set nor required), so the mirror write landed unscoped across tenants. false now returns :tenant_required like nil (2026-07-14).
  • Sink-selected actions can no longer bypass tenancy. A new ValidateActionMultitenancy compile verifier rejects multitenancy :bypass / :bypass_all on the host's primary read, create, destroy, and the SCD2 close action of a multitenant resource — Ash would otherwise ignore the tenant the sink passes and mirror every tenant unscoped (and a :bypass read would let a bulk_update/bulk_destroy match and mutate another tenant's rows), despite a valid multitenancy block. :enforce and :allow_global remain permitted (2026-07-14).
  • The multitenancy discriminator column is now shape-checked. Under strategy :attribute, ValidateMultitenancy rejects a sensitive-classified or binary-storage-typed multitenancy attribute — Ash force-sets it to the plaintext tenant and filters reads on it, so an encrypted/binary column would store/compare a mismatched value and silently mis-scope (reads return empty). AshCloak-encrypted attributes are already rejected by Ash's own verifier (2026-07-14).

0.2.0 - 2026-07-09

Added

  • ValidateTenantSource compile-time verifier — a resource declaring non-global Ash multitenancy must declare a replicant tenant source (tenant_attribute or tenant_mfa). Without one, every mirror write is attempted with tenant: nil and halts fail-closed (:tenant_required) at runtime; this gate moves that failure to build time. It is the converse of ValidateMultitenancy (which checks the shape of a declared discriminator).

Fixed (closeout review, 2026-07-08 — /review-autopilot --fix)

  • Snapshot fails closed on an empty resolver index — handle_snapshot/3 and handle_snapshot_complete/2 now share the handle_transaction/2 fail-closed guard (a degenerate/misloaded index no longer silently drops a backfill while advancing the checkpoint).
  • on_truncate :mirror clears tenant-blind — was a TenantRequired dead-end for non-global attribute-multitenant resources; now a quoted raw DELETE on the mirror table (matching the snapshot redo-safety clear).
  • Full telemetry contract — the [:ash_replicant, :snapshot, :batch] / [:snapshot, :complete] events (previously never emitted), :sink,:halted error_class, and :sink,:applied change_count + duration measurements are now emitted (change_count counted single-pass).
  • transaction?: false on the per-record upsert (the sink owns the outer transaction the action joins).

Documented (closeout review)

  • Tenant-scoped source tables must be REPLICA IDENTITY FULL — a tenant-scoped delete / PK-changing update resolves the tenant from old_record, which is key-only under the default replica identity (else the sink halts fail-closed :tenant_required). Documented in AGENTS Critical Rule 2, the tenant_attribute DSL doc, README, and usage-rules; locked by a key-only-old_record red-gate.

Optimized (post-closeout, 2026-07-09)

  • Snapshot bulk path computes its reflection once per batch — the non-tenant bulk upsert derives the {skip, cloak, attribute-name} reflection a single time (Resolver.upsert_reflection/1 + Resolver.upsert_input/2) instead of re-deriving it per row; attrs_for_upsert/2 is retained for single-record callers. Behavior unchanged (F13).
  • Delete path is a single atomic bulk_destroy — Apply.destroy_by_pk/3 issues one DELETE ... WHERE pk (strategy: [:atomic, :stream], transaction: false) instead of read-then-destroy, falling back to per-record streaming when a host destroy action carries non-atomic changes. The nil-PK fail-closed guard, per-row tenant scoping, and idempotent-on-absent-row semantics are preserved (F14).

0.1.0 - 2026-07-08

First release: the complete Ash Replicant.Sink adapter with effect-once semantics, fail-closed multitenancy, AshCloak integration, and compile-time sensitive-column verification.

Added

  • Ash resource extension (AshReplicant.Resource) — a replicant do ... end DSL section for marking AshPostgres resources as CDC mirror targets. Options: source_table, source_schema, tenant_attribute, tenant_mfa, sensitive, skip, on_truncate, on_schema_change, upsert_identity.

  • Checkpoint macro (AshReplicant.Checkpoint) — generates an AshPostgres resource backing the ash_replicant_checkpoints table (one row per slot, tracking the durable commit_lsn watermark). Bound to the host's repo and domain at compile time.

  • Sink-config macro (AshReplicant.Sink) — generates a Replicant.Sink implementation with repo, domains, checkpoint resource, and slot_name baked in. The slot_name is the single source of truth for the replication slot (not a start_link option) and keys the resolver index.

  • Resource resolver (AshReplicant.Resolver) — maps {schema, table} pairs to resources, built from the sink's domains. The index is cached in :persistent_term and accessed by the sink's transaction handler.

  • Sink action applier (AshReplicant.Apply) — applies changes to mirror resources: upsert by PK, destroy, truncate per policy. Actions are the host's own resource actions; the sink invokes them with authorize?: false at the boundary (the host's Ash policies still guard those actions for application callers; the flag exempts only the sink's in-transaction mirror writes from re-gating). Tenant is passed per-row.

  • Compile-time verifiers — enforce critical rules:

    • ValidateSensitive: each sensitive column maps to an AshCloak-encrypted attribute, a binary-storage attribute, or is skipped.
    • ValidateMultitenancy: a multitenant resource with a tenant_attribute has a plaintext, declared discriminator; the tenant is never classified or skipped.

  • Value-free error & telemetry boundaries — sink failures and halt paths carry structure (error reason, table name, LSN) only. No row values, PKs, tenant names, or raw data appear in logs, errors, or telemetry. Column names are strings, never atoms.

  • Effect-once transaction model — each Replicant.Transaction applies in one Repo.transaction: skip by commit-LSN watermark, apply rows, upsert checkpoint atomically. Failure rolls back; on resume, un-acked WAL re-streams and dedups against the durable checkpoint. Proven by crash-injection tests (loss = 0, effect-dup = 0).

  • Documentation — CLAUDE.md, AGENTS.md, README.md, CHANGELOG.md, usage-rules.md, CONTRIBUTING.md, LICENSE, NOTICE; tracked charter at docs/CHARTER.md (only /docs/superpowers/ lifecycle artifacts are local-only).