hecks 1.1.0 → 1.3.0

data/lib/hecks/fuzzing/value_generator.rb

@@ -53,6 +53,51 @@ module Hecks
       # they're included so a real generated sequence occasionally
       # produces the value at all, since nothing had, repo-wide, before.
       INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648, 2**100, -(2**100)].freeze
+      # BUG#35 (QualityControl QA ledger, `lease-clock-json-precision`) —
+      # a Bignum edge case (`2**100`, above) landing on an Integer-typed
+      # CLOCK or COUNT reading fires the already-catalogued `Json::Num`/
+      # f64 precision-loss class (`rust/src/kernel/json.rs`'s
+      # `parse_number` parses every number through `s.parse::<f64>()`
+      # before any target-type conversion runs, and `Json::Num` is a
+      # plain `f64` end to end — see that file's own header) on a NEW
+      # site every time a new clock/count-shaped field is authored,
+      # without adding any new coverage: both engines already refuse
+      # (`TypeMismatch`, out of `i64` range either way) for this shape,
+      # `tenant_ledger`'s own NOTES.md already logged the identical class
+      # on a stored money attribute, and `spec/support/
+      # rust_conformance_helpers.rb`'s own `reduce_to_wire_precision`
+      # already documents and normalizes past the wire format's own loss
+      # for a query's echoed args. An exact-integer Rust JSON
+      # deserialization path was considered and rejected as this
+      # generator's own fix instead: `Json::Num(f64)` is pattern-matched
+      # throughout `rust/src/kernel` (query_comparators.rs,
+      # query_ordering.rs, read_model.rs, named_query.rs, this kernel's
+      # own `Fielded` impl, arithmetic overflow checks) and emitted by
+      # codegen (`rust/project/reactions.rb`, `rust/codegen/src/
+      # reactions.rs`) — adding a second, exact-integer numeric variant
+      # would mean auditing and updating every one of those sites, a
+      # refactor of the JSON layer itself, not a one-domain fix (exactly
+      # the ledger's own stated concern: "risks affecting every other
+      # domain's large-integer handling"). So instead, per the ledger's
+      # own sanctioned fallback: an Integer-typed field whose name reads
+      # as a clock or a count is capped to a narrower, still-real
+      # edge-case pool below (still exercises the ordinary i32
+      # boundaries, just never a value past f64's own 2**53 exact-
+      # integer ceiling) — every OTHER Integer-typed field (a money
+      # amount, an identity sequence, anything not clock/count-shaped)
+      # still draws from the full `INTEGER_EDGE_CASES` pool above,
+      # unchanged.
+      SAFE_INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648].freeze
+      # Matched against the value object's own declared name plus the
+      # attribute's own name (`value_for`'s `"#{context} #{attribute.
+      # name}"`, e.g. "LeaseInstant value", "RetryCount value") — a
+      # clock reading ("instant"/"clock"/"expir(es/y)"/"ttl"/"now"/
+      # "timestamp"/"epoch") or a quantity capped by a policy ("count").
+      # Deliberately narrow: matches the ledger's own "clock/count"
+      # wording exactly, not every plausibly-large-looking name (an
+      # "amount"/"cents"/"sequence" field is not clock/count-shaped and
+      # keeps the full Bignum edge-case pool).
+      CLOCK_OR_COUNT_NAME_PATTERN = /clock|instant|expir|ttl|\bnow\b|timestamp|epoch|count/i
       # NaN and +/-Infinity — the real find (see `spec/runtime/
       # numeric_boundary_spec.rb`): `Value::Coercion#check_numeric_fields`
       # used to let all three sail through untyped-checked (each really
@@ -148,7 +193,7 @@ module Hecks
       def primitive(type_name, random:, name: nil)
         case type_name
         when "String"  then string_value(random, name: name)
-        when "Integer" then integer_value(random)
+        when "Integer" then integer_value(random, name: name)
         when "Float"   then float_value(random)
         when "TrueClass", "FalseClass" then random.rand(2).zero?
         else raise ArgumentError, "ValueGenerator does not know primitive type #{type_name.inspect}"
@@ -172,12 +217,19 @@ module Hecks
       # sequence that can never get past one never reaches the state a deeper
       # bug would need. Zero and negative are still real, reachable outcomes —
       # via the edge-case pool, deliberately, not by starving them entirely.
-      def integer_value(random)
-        return INTEGER_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+      def integer_value(random, name: nil)
+        if random.rand < EDGE_CASE_PROBABILITY
+          pool = clock_or_count_shaped?(name) ? SAFE_INTEGER_EDGE_CASES : INTEGER_EDGE_CASES
+          return pool.sample(random: random)
+        end
 
         random.rand(1..1000)
       end
 
+      def clock_or_count_shaped?(name)
+        name.to_s.match?(CLOCK_OR_COUNT_NAME_PATTERN)
+      end
+
       def float_value(random)
         return FLOAT_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
 

data/lib/hecks/fuzzing.rb

@@ -10,3 +10,9 @@ require_relative "fuzzing/invalid_value_generator"
 require_relative "fuzzing/sequence_generator"
 require_relative "fuzzing/replay"
 require_relative "fuzzing/properties"
+require_relative "fuzzing/rotation_priority"
+require_relative "fuzzing/sweep_depth"
+require_relative "fuzzing/persistence_parity"
+require_relative "fuzzing/form_census"
+require_relative "fuzzing/target_capabilities"
+require_relative "fuzzing/structural_skips"

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -284,8 +284,20 @@ Hecks.bluebook "Bluebook" do
              template: "{command} refused — {field} is {current}, and {command} moves it only from {allowed}"
       member refusal: "TypeMismatch", site: "value_object_shape",
              template: "{name} is a {type} — pass its fields as an object, not {offered}"
-      member refusal: "TypeMismatch", site: "reference_as_object",
-             template: "{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}"
+      # RENAMED FROM `reference_as_object` (BUG#27, QualityControl ledger) —
+      # a reference command argument that is an object was never the only
+      # wrong shape, only the first one anyone noticed: a bare Boolean,
+      # Array, or `null` used to sail past this refusal entirely, get
+      # `.to_s`'d into a lookup key by `CommandRules::References#
+      # reference_key` ("true", "false", "[8, 8]"), and answer NotFound (or,
+      # for `null`, skip the lookup outright and answer whatever the
+      # command's own `given` said instead) — a shape error misreading as a
+      # missing record. `{offered}` now names what actually arrived; the
+      # Hash/Value case still renders "an object" (Value::Coercion's own
+      # `reference_shape_description`), so the wording already pinned byte
+      # for byte in spec/runtime/reference_shape_spec.rb is unchanged.
+      member refusal: "TypeMismatch", site: "reference_wrong_shape",
+             template: "{command} refused — a reference is an id, and {attribute} arrived as {offered}{known_by}"
       member refusal: "TypeMismatch", site: "multi_field_scalar",
              template: "{type} has multiple fields and cannot stand in for a scalar"
       member refusal: "TypeMismatch", site: "composite_identity",
@@ -322,6 +334,9 @@ Hecks.bluebook "Bluebook" do
                        "{field} this ask is scoped to"
       member refusal: "Unauthorized", site: "role_mismatch",
              template: "{command} refused — role: {role}, and the caller stated {caller_role}"
+      member refusal: "Unauthorized", site: "cross_tenant_reference",
+             template: "{aggregate} {field} is {tenant}, but {attribute} names a {target} whose own " \
+                       "{target_field} is {other} — a cross-tenant reference"
       member refusal: "AttributeAbsent", site: "absent_read",
              template: "{aggregate} {field} is absent on this record — declared, not optional, and " \
                        "added since it was written. Backfill it in a translation (backfill :{field}, " \

data/lib/hecks/naming.rb

@@ -39,6 +39,47 @@ module Hecks
           .downcase
     end
 
+    # AN IDENTIFIER AS A PERSON WOULD SAY IT — `ATMCard` -> "ATM card",
+    # `AccrueInterest` -> "Accrue interest", `daily_limit` -> "Daily
+    # limit", `Back office` -> "Back office". The same two word-boundary
+    # splits `snake` uses, with a space instead of an underscore — plus
+    # the one thing `snake` cannot give back: an all-caps run stays an
+    # acronym ("ATM", "KYC") instead of being lowercased into a word
+    # nobody says ("Atm"). First word capitalized, the rest lowercased,
+    # so a headword reads as sentence case whatever casing it was
+    # declared in.
+    def words(text)
+      parts = text.to_s
+                  .tr("_", " ")
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1 \2')
+                  .split
+      parts.each_with_index.map do |part, index|
+        next part if part.match?(/\A[A-Z]{2,}\z/)
+
+        index.zero? ? part.capitalize : part.downcase
+      end.join(" ")
+    end
+
+    # "A, B, and C" / "A or B" — the Oxford-comma list every English
+    # sentence a projection writes wants; lived in `NarrateProjector`
+    # alone until a second projection needed it.
+    def to_sentence_list(items, conj: "and")
+      case items.size
+      when 0 then ""
+      when 1 then items[0].to_s
+      when 2 then "#{items[0]} #{conj} #{items[1]}"
+      else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
+      end
+    end
+
+    # The vowel-LETTER heuristic — safe here for the same reason
+    # `Projections::Statements#article` gives: a construct name is a
+    # plain word, never "hour" or "university".
+    def a_or_an(word)
+      %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
+    end
+
     # The name a COLLECTION of something takes.
     #
     # There were two of these and one was wrong. A read model's gathered heads
@@ -102,10 +143,37 @@ module Hecks
       text.include?(".") ? text.split(".", 2).last : text
     end
 
+    # DOMAIN, AGGREGATE, then the REST dot-joined into one command path.
+    #
+    # The `::` boundary between domain and aggregate is unambiguous by
+    # construction — every caller here has already prefixed the domain
+    # itself (`PolicyInterpreter#deliver`, `SagaInterpreter#qualified`,
+    # `Router#dispatch`'s own rebuilt string) before this ever runs. A
+    # THIRD `::` segment can still show up past that boundary: a bare
+    # `ScopedConstant` naming a port operation (`command_ref`'s own
+    # comment — `Aggregate::Port::Operation`, three colon-joined
+    # segments with no `.` of its own) only gets its LAST `::` rewritten
+    # to `.` there, at DSL-build time, because nothing at that point
+    # knows yet whether the constant names a port operation or a
+    # domain-qualified command (`Domain::Aggregate::Command`, the OTHER
+    # shape `command_ref` documents) — both are textually identical.
+    # Here, past the already-resolved domain boundary, any leftover
+    # `::` is unambiguous: it is that same rewrite artifact, and folding
+    # it into the dot-joined tail recovers exactly the
+    # `Aggregate::Port.Operation` shape a working port dispatch already
+    # expects (`spec/port_operation_interpreter_spec.rb`'s own
+    # `"Payments::Payment.PaymentGateway.Receive"`). `Outbox::Fanout
+    # .kind_for` and `ReactionInvocation#resolve_target` both already
+    # assume this contract on their own end; this is what actually
+    # delivers it to them.
     def split_verb(verb)
       path, command = verb.to_s.split(".", 2)
-      domain, aggregate = path.to_s.split("::", 2)
-      return nil unless domain && aggregate && command
+      return nil unless path && command
+
+      domain, aggregate, *rest = path.to_s.split("::")
+      return nil unless domain && aggregate
+
+      command = "#{rest.join('.')}.#{command}" unless rest.empty?
 
       [domain, aggregate, command]
     end

data/lib/hecks/ports/persistence/append_only.rb

@@ -147,6 +147,17 @@ module Hecks
           yield
         end
 
+        # ONLY an adapter advertising `:cross_process_lock` (PostgresEra —
+        # see ADR 0036) implements this; `run_dispatch_order_with_isolation`
+        # (runtime/interpreting.rb) checks `capabilities` before ever
+        # calling it, so the plain `yield` fallback here only guards
+        # against a stray direct call, not the real dispatch path.
+        def with_write_lock(&)
+          return @adapter.with_write_lock(&) if @adapter.respond_to?(:with_write_lock)
+
+          yield
+        end
+
         # THE OUTBOX CONTRACT — four optional adapter methods, probed
         # together the way `save_saga`/`delete_saga`/`each_saga` are
         # (`Registry::SagaPersistence`): an adapter either has an outbox

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/provisioning.rb

@@ -287,6 +287,56 @@ module Hecks
             raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{e.message.strip}"
           end
 
+          # THE FENCE HAS TO BE ABLE TO BITE THIS CONNECTION, OR NOTHING
+          # ensure_base! BUILDS MEANS ANYTHING. The whole write-fence is
+          # row-level security (FORCE ROW LEVEL SECURITY above, plus
+          # advance_era!'s one INSERT policy), and Postgres exempts a
+          # superuser — or any role granted BYPASSRLS — from every policy
+          # on every table, unconditionally: FORCE only narrows the
+          # OWNER's exemption and has no lever against either of those.
+          # Found live, not reasoned about (BUG#24): the QA ledger's own
+          # `.world` named a bare database, so every session connected as
+          # the machine's default Postgres user — a superuser — and an
+          # old checkout wrote its own superseded era straight through
+          # two mints, 37 rows no newer head could read, and nothing
+          # warned. Asked of the catalog ONCE, at boot, BEFORE anything
+          # is provisioned: the answer is a fact about the ROLE, not about
+          # any table, so there is nothing to wait for and nothing to
+          # half-build first.
+          #
+          # Refuses by default — quiet divergence is the enemy — naming
+          # the role and both ways out. `allow_superuser` boots anyway,
+          # but says so on stderr on EVERY boot, because the only guard
+          # left standing then is PostgresEra#append's own in-process
+          # superseded-era check (the belt to this suspender), and an
+          # operator reading the log deserves to know which one they are
+          # relying on. Presence-over-truthiness for the setting itself
+          # is `PostgresEra.setting`'s job (the caller's); here a truthy
+          # value opts in and anything else does not.
+          def check_fence_applies!(allow_superuser: false)
+            row = @db.exec("SELECT rolname, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user")[0]
+            exempt = []
+            exempt << "a superuser" if row["rolsuper"] == "t"
+            exempt << "granted BYPASSRLS" if row["rolbypassrls"] == "t"
+            return if exempt.empty?
+
+            role = row["rolname"].inspect
+            unless allow_superuser
+              raise Runtime::WiringError,
+                    "cannot boot #{@domain}: PostgresEra's era write-fence is row-level security, and this " \
+                    "connection's role #{role} is #{exempt.join(' and ')} — Postgres exempts it from every " \
+                    "policy, FORCE included, so an old checkout connected this way keeps writing a superseded " \
+                    "era and nothing refuses. Connect as an ordinary role instead (database " \
+                    "\"postgres://<role>@<host>/<db>\" in the .world — a non-superuser OWNER still provisions " \
+                    "and mints), or declare `allow_superuser true` in the same persisted_by block to boot with " \
+                    "the fence void, on the record."
+            end
+
+            warn "[hecks] #{@domain}: booting PostgresEra as #{role}, #{exempt.join(' and ')}, under " \
+                 "allow_superuser — the era write-fence is void for this connection; only this process's own " \
+                 "superseded-era check (PostgresEra#append) stands between an old checkout and a superseded era"
+          end
+
           # Nothing provisioned yet — build it. Provisioned and owned —
           # keep it current. Provisioned by SOMEONE ELSE — this is an app
           # role, and the owner has already done this work.

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -22,6 +22,12 @@ module Hecks
           def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+            # FIRST, before ensure_base! provisions or verifies anything —
+            # the one point every PostgresEra boot passes through, and the
+            # earliest at which the connection's own role is known. See
+            # check_fence_applies!'s own header (BUG#24) for why a
+            # superuser connection refuses here by default.
+            lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
             lineage.ensure_base!
             # Both spellings honored, key? first — never `||`, which cannot
             # tell a genuinely stored `false` apart from an absent key (see
@@ -78,6 +84,14 @@ module Hecks
               # called with a superseded ordinal.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: matched[:ordinal]) if role
               registry.resolved_eras[bluebook.name] = matched[:ordinal]
+              # ...and the boot REMEMBERS that it is superseded, not only
+              # which era it is: `RepositoryFactory.build` hands this to
+              # the adapter as `superseded_by:`, and `PostgresEra#append`
+              # refuses on it before issuing the INSERT. That is the
+              # in-process half of "may not keep WRITING" — the half that
+              # holds even for a connection the RLS fence cannot bite
+              # (a superuser under allow_superuser; BUG#24).
+              registry.superseded_eras[bluebook.name] = latest[:ordinal]
               return
             end
 

data/lib/hecks/ports/persistence/plugins/era/postgres_era.rb

@@ -2,6 +2,7 @@ require "json"
 
 require_relative "../../../../adapters/driven/sql_query_builder"
 require_relative "../../../../adapters/driven/postgres/outbox"
+require_relative "../../../../adapters/driven/postgres/reconnect"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "../../../../ports/persistence/append_only"
@@ -42,10 +43,19 @@ module Hecks
     class PostgresEra
       include SqlQueryBuilder
       include Adapters::PostgresOutbox
+      include Adapters::PostgresReconnect
 
       attr_reader :aggregate
 
-      def persistence_capabilities = [:atomic_put]
+      # `:cross_process_lock` tells `Interpreting#run_dispatch_order_with_isolation`
+      # (runtime/interpreting.rb) this repository can hold a REAL
+      # cross-process lock for the whole dispatch order itself, via
+      # `with_write_lock` below — so it should use that instead of the
+      # in-process `AggregateLock` `Mutex` every other non-CAS repository
+      # falls back to. See ADR 0036: that in-process Mutex is invisible
+      # to `rust/host` dispatching against the same PostgresEra-bound
+      # tables from a separate OS process.
+      def persistence_capabilities = %i[atomic_put cross_process_lock]
 
       # The capability idiom: only PostgresEra answers true, and only
       # PostgresEra carries an era_check! for the boot gate to delegate to.
@@ -148,11 +158,35 @@ module Hecks
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
+        @settings  = settings
         @db = self.class.connect_for(aggregate.name, settings)
         # The domain names the journal (one journal per lineage). The
-        # factory injects it; a directly-instantiated adapter (specs,
-        # consoles) journals under the aggregate's own name.
-        @domain = self.class.setting(settings, :domain, default: aggregate.storage_name).to_s
+        # factory injects it as the owning bluebook's own declared name
+        # (`RepositoryFactory.build`'s own `domain` positional arg —
+        # `bluebook.name`, confirmed at `outbox.rb`'s own call site —
+        # never this default in real dispatch). This default exists only
+        # for a directly-instantiated adapter (specs, consoles) that
+        # skips the factory.
+        #
+        # When the aggregate DOES have an owning chapter (`hecks_owner`
+        # set — true for any aggregate sealed through a real bluebook,
+        # even if this adapter itself was built by hand), default to the
+        # chapter's own declared PascalCase name. That's the same string
+        # `rust/host`'s `pg_advisory_xact_lock` key derives from
+        # (`HECKS_DOMAIN`, deploy-time-set to `world.domain`) — the
+        # aggregate's own snake_case `storage_name` silently disagreed
+        # with it (`hashtext` is byte-sensitive: `"chess"` and `"Chess"`
+        # never collide), which is ADR 0036 Blocker 1.
+        #
+        # When there's no owning chapter at all (a bare
+        # `AggregateBuilder` fixture built outside any real bluebook —
+        # `hecks_owner` is only ever stamped by chapter construction, see
+        # `traits.rb`'s `hecks_owner = self`) there is no chapter name to
+        # match Rust against in the first place, so fall back to the
+        # aggregate's own name, same as before this ADR.
+        @domain = self.class.setting(
+          settings, :domain, default: aggregate.hecks_owner&.name || aggregate.storage_name
+        ).to_s
         @lineage = Lineage.new(@db, @domain)
         @lineage.ensure_base!
         # The era gate resolves which era this boot IS (an old checkout
@@ -175,6 +209,20 @@ module Hecks
         # promise.
         @era = settings.key?(:era) ? settings[:era] : settings["era"]
         @era ||= @lineage.current_era
+        # THE IN-PROCESS HALF OF THE ERA FENCE. `EraResolver.check!` sets
+        # `registry.superseded_eras[domain]` for a held-but-superseded
+        # boot only, and `RepositoryFactory.build` merges it in here as
+        # `superseded_by:` — so this is nil for every current-era boot AND
+        # for a directly-instantiated adapter (specs, consoles), which,
+        # like `era:` above, self-resolves rather than being told. When
+        # set, `append`/`atomic_put` refuse BEFORE issuing an INSERT (see
+        # `refuse_superseded_write!`): the RLS fence already refuses the
+        # same write for an ordinary role, but a superuser walks through
+        # RLS (BUG#24), and this checkout's own knowledge that it is stale
+        # is the one guard no role attribute can void. Same coalescing as
+        # `era:` — the key is always PRESENT from the factory, holding nil
+        # for the ordinary case.
+        @superseded_by = settings.key?(:superseded_by) ? settings[:superseded_by] : settings["superseded_by"]
         # Unconditional and idempotent, regardless of era — belt-and-
         # suspenders self-healing (compile_head! already ensures this for
         # a freshly-minted era's own name; ensure_first_head! for era 1's)
@@ -274,6 +322,18 @@ module Hecks
         head_phase(declared, uncached, ids, args)
       end
 
+      # ADR 0036's actual fix — see `persistence_capabilities` above.
+      # Wraps the WHOLE dispatch order (hydrate through save), not just
+      # `append`'s own transaction below: `lock_writes!` has to be held
+      # before hydrate even starts, or two cross-process writers can
+      # both hydrate unlocked and race for the write, each blind to the
+      # other. `transaction` (via `include Adapters::PostgresOutbox`) is
+      # already re-entrant — `append`/`atomic_put`'s own inner
+      # `transaction do ... end`, deep inside the block below, joins
+      # this SAME transaction instead of opening/committing its own, so
+      # the advisory lock stays held until this whole block returns.
+      def with_write_lock(&block) = transaction { lock_writes!; block.call } # rubocop:disable Style/Semicolon
+
       # HELD FOR THE WHOLE TRANSACTION, not just around the INSERT — the
       # ordinal is assigned by the column's own `nextval()` default, inside
       # this same statement, so the lock has to already be held before that
@@ -290,8 +350,12 @@ module Hecks
       # still runs, cheaply, during AppendOnly#recover!'s full replay on
       # every boot (see `project` below), and a second write there would
       # make that replay pay real DB cost for a snapshot that's already
-      # correct.
+      # correct. When `with_write_lock` above already drove this whole
+      # dispatch, `lock_writes!` here is a harmless re-acquire of the
+      # same already-held (per-session-reentrant) advisory lock; a bare
+      # `repository.save` outside a full dispatch still takes it fresh.
       def append(entry)
+        refuse_superseded_write!
         transaction do
           lock_writes!
           append_and_project!(entry)
@@ -299,11 +363,27 @@ module Hecks
         entry
       end
 
+      # BEFORE the transaction, before the lock, before the INSERT — a
+      # superseded checkout takes nothing and touches nothing. Reads are
+      # deliberately untouched: `EraResolver.check!`'s own contract for an
+      # old checkout is "may keep BOOTING and READING, but may not keep
+      # WRITING", and the head views it reads through are its own era's.
+      def refuse_superseded_write!
+        return unless @superseded_by
+
+        raise Runtime::WiringError,
+              "cannot write #{table} for #{@domain}: this checkout booted era #{@era}, which era " \
+              "#{@superseded_by} has superseded — its shape was replaced by a mint, and a write here would " \
+              "land in a partition no newer head reads. Reads still work; pull the current bluebook and " \
+              "reboot to write again."
+      end
+
       # Outcome detection, journal append and every derived projection share
       # the SAME transaction and domain write lock. The lineage-aware head
       # determines whether this id is already visible; no repository `find`
       # occurs before entering this adapter-native operation.
       def atomic_put(entry, insert_only: false)
+        refuse_superseded_write!
         status = nil
         transaction do
           lock_writes!

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -13,13 +13,16 @@ module Hecks
           settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
                      .reject { |key, _| key.to_sym == :role }
           registry.check_settings(bind, settings)
-          # The domain and the resolved era ride along after the
-          # declared-settings check: a lineage adapter journals per
-          # DOMAIN and writes into its own ERA's partition — neither of
-          # which a world's settings carry.
+          # The domain, the resolved era, and (for an old checkout) the era
+          # that superseded it ride along after the declared-settings
+          # check: a lineage adapter journals per DOMAIN, writes into its
+          # own ERA's partition, and refuses to write at all once that era
+          # is superseded (`PostgresEra#append`, BUG#24) — none of which a
+          # world's settings carry.
           adapter = registry.adapter_class(bind.adapter)
                             .new(aggregate: aggregate,
-                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s]),
+                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],
+                                                           superseded_by: registry.superseded_eras[domain.to_s]),
                                  root:      registry.root)
           repository = AppendOnly.new(adapter)
           recover ? repository.recover! : repository