Why

docs/correctness.md promises at-least-once execution and tells external
systems to hold stable idempotency keys. Nothing in the repository showed that
duplicate arriving anywhere. A contract clause nobody can watch fire is
decoration, so this adds the artifact that makes it fire on demand, and shows
the documented remedy absorbing it.

This is the Ruby counterpart of
solid-objects-js#26,
which implements
solid-objects-js#23.
Same proof, same shape, same numbers.

No runtime code changes. This is an example, a unit test, a CI step, and two
lines of prose.

What the demo does

bundle exec rake at_least_once runs examples/at_least_once/demo.rb against
a temporary SQLite file:

1. One actor turn increments count and stages a record effect in the same
   commit.
2. A child process claims the effect, writes the delivery to an external sink
   file, then calls Process.exit!(1) between the sink write and the
   acknowledgement. The sink holds the delivery; the effect row never
   completes.
3. After the liveness threshold, a second child calls
   SolidObjects::ProcessRegistry.cleanup_dead (production runs this on
   dead_process_cleanup_interval), reclaims the released effect, and delivers
   again.

Phase one runs the sink with deduplication off. Phase two repeats the same
crash with a guard on the stable effect id.

{
  "duplicate": {
    "state_commits": 1,
    "sink_deliveries": 2,
    "same_effect_id": true,
    "attempts": [1, 2]
  },
  "remedy": {
    "state_commits": 1,
    "sink_deliveries": 1
  }
}

The state commit happens exactly once in both phases. That is the sharpest
line of the proof: the actor kept its exactly-once story while the outside
world saw the delivery twice, and only a consumer-side guard on context.id
collapsed it.

The crash point

SolidObjects.register_effect(:record) do |_arguments, context|
  AtLeastOnceSink.record(
    path: sink_path.to_s,
    effect_id: context.id,
    attempt: context.attempt,
    deduplication: deduplication.to_sym
  )
  # A crash between the external write and the acknowledgement: the sink
  # has the delivery, the effect row never completes.
  Process.exit!(1) if mode == "crash"
  nil
end

context.id is stable across attempts and context.attempt reads 1 then 2,
which is exactly what an external consumer needs in order to deduplicate.

Observed failures

The sink test was written first. With examples/at_least_once/sink.rb absent,
bundle exec rake test TEST=test/unit/at_least_once_sink_test.rb:

test/unit/at_least_once_sink_test.rb:5:in 'Kernel#require_relative': cannot load such file -- .../examples/at_least_once/sink (LoadError)

A missing file is a weak failure, so the guard was also removed from a
complete sink. The unit test then failed on the assertion under test rather
than on load:

Failure:
AtLeastOnceSinkTest#test_applies_a_replayed_effect_id_once_when_deduplication_is_on [test/unit/at_least_once_sink_test.rb:35]:
Expected true to not be truthy.

3 runs, 6 assertions, 1 failures, 0 errors, 0 skips

The demo is not self-fulfilling either. With the same guard removed,
bundle exec rake at_least_once fails at the remedy phase:

examples/at_least_once/demo.rb:28:in 'Object#prove': proof failed: the stable effect id absorbed the duplicate (RuntimeError)

Restoring the guard turns all three green.

Files

Wiring

• bundle exec rake at_least_once runs it.
• CI runs it in the SQLite job, after bundle exec rake.
• docs/correctness.md links it from the handler idempotency section it makes
  observable.
• CHANGELOG.md records it under Unreleased.

docs/roadmap.md is untouched. The gem's claims about itself did not move;
this makes an existing claim observable.

Effects

• API: none. No public surface changes.
• Correctness: none. The demo asserts existing behavior.
• Security: none. The demo runs against a temporary SQLite file and permissive
  authorization inside its own process.
• Migration and compatibility: none.

Validation

• bundle exec rake (test, standard, rubocop, rbs, steep, security): pass.
• bundle exec rake at_least_once: four consecutive clean runs locally.