Changelog

Copy Markdown View Source

All notable changes to this project are documented in this file.

v0.4.0 — 2026-08-09

Hardening, ops-readiness, and enhancement release. No breaking contract change for existing consumers — the minor bump carries new public observability surfaces (the telemetry default attach helper, the :worker_timeout result class, the ETS cache reference adapter) and the span-events-out-of-scope decision. Existing consumers are unchanged; all new surfaces are opt-in.

  • External-recovery adversarial-absence proof (H10): a test proving the re-execution invariant against a lying-:absent adapter, plus a normative section in documentation/external-effects.md stating the adapter MUST prove absence and the peer MUST enforce idempotency by operation key. No runtime guard — the trust is inherent to the design (ADR-0001). The library's :absent trust is safe against a correct peer.
  • Worker timeout distinguished from disconnect (H11): the committed-claim worker's 30s timeout now surfaces as a distinct :worker_timeout result_class on [:ash_onetime, :store_uncertainty], separate from :disconnected and :unknown. All three fail closed; the distinction is operational triage (pool/lock contention vs network partition).
  • Oban worker backoff + discard alert (H20, ADR-0005): the three maintenance workers (Cleanup, Partition, Reap) declare a bounded, jittered backoff/1 (30–120 s) instead of the default exponential, so transient failures retry within the retention window. A documented discard-alert SQL names the operational signal for a stranded partition roll.
  • Telemetry default attach handler (H21): AshOnetime.Telemetry.attach/0 — an opt-in helper routing the closed event surface into a downstream :metric stream for a consumer's own aggregator. No telemetry_metrics dependency; the value-free invariant is preserved.
  • Telemetry span structure (H22): documented that the library emits point events only (never span events), with the reason (:telemetry.span/3 cannot preserve the value-free invariant — it force-injects telemetry_span_context and fires :exception inside the span before any caller rescue) and a recommended consumer-applied :telemetry.span/3 wrapper.
  • Operations runbook (H23): three named procedures (backlog-stuck, partition-discard-detected, pool-saturated) with exact SQL/telemetry queries.
  • ETS cache reference adapter (H30): AshOnetime.Cache.Ets — bounded, TTL-aware, supervised, no third-party dependency. Makes the cache-degradation path reachable without a Redis dependency.
  • Admission unit tests (H31), key_source/claim property tests (H32): direct test coverage for the pure decision functions and the security-boundary invariants (the suite grows from 500 to 553 tests).
  • Runtime security-surface docs (H33): @doc on token.ex, key_source.ex, fingerprint.ex, telemetry.ex public functions.
  • CI-matrix-asserted compatibility documented (H34): CONTRIBUTING names the CI matrix as the guard against transitive semantic drift (not the dep bounds).

v0.3.0 — 2026-08-09

Security release: raises the Ash floor to the CVE-patched 3.31.1 and makes the architecture census robust to dependency framework-injection drift. Breaking dependency change — consumers on Ash 3.29.3–3.31.0 must bump Ash to ≥ 3.31.1 (the library is pre-1.0, so the minor version carries the break per the documented convention).

  • Ash floor raised to 3.31.1 (from 3.29.3). EEF-CVE-2026-70395 (predicate injection in manage_relationship belongs_to lookup disclosing secret lookup keys) and EEF-CVE-2026-69659 (memory exhaustion via unbounded keyset-cursor deserialization) affect Ash below 3.31.1; both are patched in 3.31.1. mix hex.audit — a required gate — now fails on the 3.29.3 lock. Consumers pinned to Ash 3.29.3–3.31.0 must bump Ash to ≥ 3.31.1. See ADR-0004 (Security-driven Ash floor). The CI matrix narrows from [3.29.3, 3.30.1, latest] to [3.31.1, latest].
  • Export census version-tolerance (test harness): the documented public-export census no longer breaks on Splode/Ash framework-injection drift. It derives each module's project-authored exports from its own source AST, so framework-injected functions (e.g. Splode 0.3.2's keyword_list_options?/0) are auto-classified rather than hand-maintained, and the census guards exactly the project-owned public surface. This fixed a CI failure present since v0.1.0 across all Ash-matrix cells. Also fixes a seed-dependent flake in the ARCH-1 Splode-membership assertion (force-loads the module before the check).

v0.2.0 — 2026-08-09

Feature release: the DPoP replay fence, forward response-partition maintenance (SEC-5/6), and notebook-per-concern docs. New user-facing capabilities (minor bump); no contract break since v0.1.1 — existing consumers are unchanged, all new surfaces are opt-in.

  • DPoP replay fence (admission): add commit: :independent (default :with_action) on :one_time_nonce protections. When set, the nonce claim commits in its own transaction before the action body runs (via the existing claim_committed worker), so a body failure cannot make the proof reusable — RFC 9449 §11.1 request-attempt scope. A reused proof within the acceptance window is rejected with :nonce_already_used via the existing collision path. Opt-in: existing nonce consumers are byte-for-byte unchanged. Rejected (compile error) on :idempotency. No new table, migration, error code, or telemetry event. See ADR-0003 (Independent-commit nonce). Operational note: the claim_committed worker uses a +1 connection checkout per in-flight protected request and a 30s timeout (fails closed); size the pool accordingly.
  • SEC-5 (data-layer): add forward monthly response_payloads partition creation (Store.roll_partitions/2, mix ash_onetime.roll_partitions, AshOnetime.Oban.PartitionWorker) plus a one-time forward migration (mix ash_onetime.gen.roll_forward). The install migration generates a fixed 13-month window; once retention exceeds it, payloads routed to _default and were never dropped (the drop path excludes _default), silently defeating bounded retention (ADR-0001:65 "reuse after retention is a new execution"). The roll keeps the window ahead of retention; the forward migration back-fills elapsed partitions, adds the index, and drains past-retention payloads stranded in _default via a claim-scoped delete. The roll is idempotent and concurrency-safe (advisory-locked, bounded lock_timeout). Existing installs run the forward migration once.
  • SEC-6 (data-layer): add an index on ash_onetime_idempotency_claims(response_partition). Cleanup's partition-empty check was a full scan per partition per cycle.
  • Telemetry: add :partitions_created to the [:ash_onetime, :cleanup] event's result-class enum (closed-schema extension, pinned by a mutation fixture). See Telemetry.

v0.1.1 — 2026-08-08

Adoption polish: a runnable Livebook walkthrough, richer Igniter installer, and adoption docs. No contract change; safe minor bump from v0.1.0.

  • Add runnable Livebook notebooks — one per concern (idempotency, one-time nonces, external recovery) — covering fresh execution, replay, fingerprint conflict, nonce spend/reuse, and the external-effect protocol end-to-end against a real PostgreSQL. Each notebook's code is regression-pinned by test/ash_onetime/livebook_walkthrough_test.exs.
  • Extend the Igniter installer with a repeatable --resource MyApp.MyResource flag that wires AshOnetime.Resource into a resource and scaffolds a starter onetime block. Non-resource targets and missing modules are rejected loudly instead of silently no-op'ing.
  • Add adoption docs: Recipes, Telemetry, Upgrading, and FAQ. Add a README "When to use this vs. hand-rolled idempotency" section and a "Try it" livebook pointer.
  • Reorder Getting started to lead with the consumer quickstart (install → protect → handle the result); move the test-DB harness to CONTRIBUTING. Fix the stale "not published yet" line (the package is live on Hex).

v0.1.0 — 2026-08-08

  • Breaking (DSL): collapse the dual limits surface into a single protect-level vocabulary. Response-size limits can no longer be declared on the response entity (response ..., limits: [...]); declare them on protect instead. The protect limits: option now accepts the full 11-key union vocabulary: max_key_bytes, max_token_bytes, max_scope_components, max_fingerprint_bytes, verifier_timeout_ms, max_cache_entry_bytes (key/verification/cache paths), and max_response_bytes, max_response_depth, max_response_nodes, max_response_entries, max_response_scalar_bytes (response payload). All keys are validated at compile time. To migrate, move any response ..., limits: [max_response_*: ...] keys onto protect ..., limits: [...].
  • Make AshOnetime.Error a Splode error of class :invalid so Ash recognizes it and preserves the typed :code through the action pipeline. Before, a protected-action failure was wrapped as Ash.Error.Unknown.UnknownError and the code (e.g. :nonce_already_used, :key_reused_with_different_request) was lost before it could reach the caller. Add AshOnetime.Error.code/1 to recover the code from a leaf or class wrapper. See documentation/errors.md for the code→HTTP table.
  • Add a caller-visible replayed-vs-fresh signal. After Ash.create/2 / Ash.run_action/2 returns, AshOnetime.replayed?/1 reports whether the result was a stored replay (true), a fresh execution (false), or carries no signal (nil — untracked execution, primitive-return action, or unprotected). The signal rides __metadata__[:ash_onetime] for tracked admission classes; :untracked is deliberately not stamped to preserve untracked transparency. See documentation/replay.md.
  • Broaden the Ash dependency requirement from ~> 3.29.0 (only 3.29.x) to >= 3.29.3 and < 4.0.0, so the package installs across the whole Ash 3.x line. The floor is 3.29.3, not 3.29.0: EEF-CVE-2026-55736 (private action arguments settable by user input) affects Ash 3.29.0–3.29.2 and is fixed in 3.29.3.
  • Add a CI compatibility matrix (.github/workflows/ci.yml), configured to run the full gate battery — including mix hex.audit — against the 3.29.3 floor, each intermediate minor, and a floating latest Ash 3.x cell on every push and pull request once the repository is pushed to a GitHub remote.
  • Establish the standalone Mix package, PostgreSQL 18 test harness, package boundary checks, accepted architecture decision, and project documentation.
  • Add the per-action Spark resource DSL, normalized introspection, precompile rejection boundary, fail-closed runtime stubs, compile-fixture battery, and mutation proofs.
  • Add PostgreSQL-authoritative idempotency and one-time nonce admission with exact operation, scope, key, fingerprint, transaction, and failure-direction invariants.
  • Add transactional CRUD and generic-action execution, classified typed response persistence, digest-bound replay, and replay-safe lifecycle enforcement. The response contract digest binds the codec options, so stored bytes cannot be reinterpreted under changed options; replayed results carry the same selected/tenant metadata as a first execution.
  • Enforce the configurable max_scope_components, max_fingerprint_bytes, and max_response_bytes limit overrides at their declared values, not only their package ceilings.
  • Add bounded canonical encoding, HMAC-SHA-256 and Ed25519 signing, trusted verification facts, self-identifying tokens, and inclusive nonce windows.
  • Add committed external-effect recovery points, stable peer operation keys, conservative ambiguous-outcome handling, and crash recovery.
  • Add unpartitioned and operation-hash-partitioned claim layouts, date-partitioned response payloads, strict bounded cleanup, deletion guards, the prune task, and optional Oban cleanup.
  • Add PostgreSQL-gated cache degradation, optional Plug header extraction, closed value-free telemetry, deterministic Igniter installation, and migration generation.
  • Add system, architecture, mutation, documentation, exact Hex archive, unpacked consumer, and dependency audit release gates, run on the pinned Elixir 1.20.2 / Erlang/OTP 29 runtime.