Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ as a new decision.)*

## Amendment (2026-09-29): every name the conformance suite defines in a host module carries one reserved prefix

Status of this amendment: proposed (2026-09-29). The record above is
Status of this amendment: accepted (2026-09-29). The record above is
accepted; this amendment does not change its status line.

Decision 5 ships the conformance suite as a test-case template that a
Expand Down Expand Up @@ -210,3 +210,44 @@ module could call them, and one in this repository did
(`test/statifier_persistence/storage/setup_ordering_conformance_test.exs`).
Such a call no longer compiles until it carries the prefix. Nothing a
generated case asserts changes.

## Note (2026-10-01, sp-lbxd): the reserved-prefix Amendment is accepted

The 2026-09-29 Amendment "every name the conformance suite defines in a
host module carries one reserved prefix" is accepted on 2026-10-01,
under the operator's standing grant to flip a record whose code has
shipped. The code that implements it shipped in statifier_persistence
0.24.0 (tag `v0.24.0`, `9f9eaa0`) under a Changed line of its changelog.
That Amendment's own status line flips in place from proposed to
accepted, and its sentence "The record above is accepted" still holds;
the record above stays accepted. Every cite below was read at
`20e59b2`, which is `main`; the only commit on `main` since the tag adds
a Note to ADR-0012 and changes nothing in `lib/` or `test/`.

What was re-read before the flip:

- **One reserved prefix.** In
`lib/statifier_persistence/testing/storage_conformance.ex`, every
module attribute and every function the `using` block defines in the
host module starts with `conformance_`, and its two nested modules are
`ConformanceRetiringSerialization` and
`ConformanceReentrantSerialization`; the one public function is
`conformance_forward_adapter_call/4`. Before the change, at `c720da0`,
the suite's attributes `@conformance_adapter`,
`@conformance_adapter_opts`, `@conformance_hash_suffix` and
`@conformance_prune_scope` already carried that spelling.
- **The contract and the aliases.** The same file's moduledoc states
the prefix as the host's contract, names the generated tests'
`adapter:` and `facade:` names, and names the six aliases and the two
ways around them.
- **The cases.**
`test/statifier_persistence/storage/reserved_prefix_conformance_test.exs`
keeps `@retire_hash`, `ReentrantSerialization` and `own_chart_a/0`
in a host module beside the suite's cases;
`test/statifier_persistence/storage/setup_ordering_conformance_test.exs`
calls `conformance_input_log_execution/2`.
- **No assertion changes.** The generated tests' names are the same set
before and after the change, and its assertion lines differ only by
the prefix.
- **The changelog.** The 0.24.0 section of `CHANGELOG.md` names the
prefix and the renamed telemetry handler under Changed.
52 changes: 51 additions & 1 deletion docs/adr/0012-retention-and-retirement.md
Original file line number Diff line number Diff line change
Expand Up @@ -860,7 +860,7 @@ database never retire the same hash.

## Amendment (2026-09-29): the per-hash lock is keyed by the store, never by the tenant

Status of this amendment: proposed (2026-09-29). The record above is
Status of this amendment: accepted (2026-09-29). The record above is
accepted; this amendment does not change its status line.

The 2026-09-28 Amendment keyed the per-hash advisory lock on
Expand Down Expand Up @@ -966,3 +966,53 @@ the SHA-256 of the using module's name.

The earlier Note's conclusion holds for both kinds: two hosts running
the suite in one database never retire the same hash.

## Note (2026-10-01, sp-lbxd): the store-keyed lock Amendment is accepted, and the suite's retiring module now carries the reserved prefix

The 2026-09-29 Amendment "the per-hash lock is keyed by the store, never
by the tenant" is accepted on 2026-10-01, under the operator's standing
grant to flip a record whose code has shipped. The code that implements
it shipped in statifier_persistence 0.24.0 (tag `v0.24.0`, `9f9eaa0`)
under a Changed line of its changelog. That Amendment's own status line
flips in place from proposed to accepted, and its sentence "The record
above is accepted" still holds; the record above stays accepted. Every
cite below was read at `20e59b2`, which is `main`; the only commit on
`main` since the tag adds the 2026-09-30 Note above and changes nothing
in `lib/` or `test/`.

What was re-read before the flip:

- **The key.** In `lib/statifier_persistence/storage/ecto.ex`,
`chart_lock/3` issues `pg_advisory_xact_lock` or
`pg_advisory_xact_lock_shared` on `@chart_lock_namespace` and
`hashtext` of `chart_store/1`'s answer, a space and the content hash,
and only when the repo's adapter is Postgres; `chart_store/1` quotes
the chart schema's `__schema__(:source)`, and its
`__schema__(:prefix)` when it has one, joined by a dot, doubling any
quote inside; `supports_chart_retirement?/1` reads the same two
values.
- **Both modes, one key.** `fetch_retired_info/2` takes `chart_lock/3`
in `:shared` mode and `retire_chart/3` in `:exclusive` mode.
- **The unit.** `lib/statifier_persistence/ecto/migrations/v01.ex`,
`up/1`, creates the charts table's unique index on `content_hash`
alone, and no later migration in that directory changes it.
- **The cases.** `test/statifier_persistence/ecto/retire_chart_race_test.exs`
carries "two stores in one database retire one hash without either
waiting" over the `Scoped` and `SharedIdScoped` hosts, whose prefixes
are `scoped` and `scoped_shared_id` (`test/support/ecto_hosts.ex`),
and "two host modules on one charts table still share the hash's
lock" over `Default` and `Bigserial`.
- **The changelog.** The 0.24.0 section of `CHANGELOG.md` names the
store-scoped key under Changed.

**The suite's retiring module.** Two sentences above still name the
conformance suite's nested module `RetiringSerialization`: the 2026-09-28
Amendment's "**Pinned by.**" paragraph and the "**The cases.**" item of
the 2026-09-29 sp-fnay Note. The change that carries ADR-0003's
2026-09-29 Amendment, "every name the conformance suite defines in a
host module carries one reserved prefix" (`20fb8bb`), renamed it
`ConformanceRetiringSerialization` in
`lib/statifier_persistence/testing/storage_conformance.ex`, where it is
defined on `main` today; read those two sentences with that name. The
module's job and the cases that use it are unchanged. This Note decides
nothing new.
Loading