statesman-solid_objects 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f47ed26baff2bc6fa7e7d750f8c804398a615ac52975c878e7d1d3ab48f6a272
+  data.tar.gz: 2e558c9c39356cb31644fa824738a894f9057221f76527fefa105514dbebe7bc
+SHA512:
+  metadata.gz: ccf1bf941913c5313d43ba39f1bd3c83a456f72f6296fae4111b1762f45a750ad3bfd381cc48f1a5d48b96f396d8968c112df0b697940a58933f00fae0832810
+  data.tar.gz: a1db9a369bdd8d7d80dd09335d6b3ab9300fb815fb77b555f5e19abebaa6adcf33d4fad9cd685d07e81f36aa0fe4d875df09d4bd16c651b9eb1932c0d357637d

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 - 2026-09-12
+
+- Add SQLite, PostgreSQL, and MySQL CI with gated version-tag publishing to
+  RubyGems through OIDC and automatic GitHub Releases.
+- Introduce a Rails-only registered-machine Statesman adapter backed by Solid
+  Objects mailboxes, fenced commit actions, and Active Record transition rows.
+- Require Solid Objects 0.14.6 for correct post-commit callback error handling.
+- Preserve ordered transition history and state queries, with serialized
+  authoritative validation and explicit default-deny authorization.
+- Offer inline or emitted after-commit callbacks with documented reconstruction,
+  transaction, and at-least-once delivery boundaries.
+- Use the stock transition schema, support initial transitions, provide an
+  authorized machine factory, reject callback write re-entry, and preserve
+  unrelated application rejection errors.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solid Objects contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+# statesman-solid_objects
+
+**Six concurrent transition attempts: one success, five domain rejections,
+zero transition conflicts.** The same synchronized race against Statesman's
+Active Record adapter produces one success and five `TransitionConflictError`s.
+
+A Rails-only Statesman storage adapter using Solid Objects mailboxes and
+transactional Active Record writes. Requires **Solid Objects 0.14.6+** and
+Statesman 13.3. Machines are reconstructed from boot registrations and
+persisted parents; this is not a drop-in replacement for every Statesman
+callback pattern.
+
+Version **0.1.0**. See [compatibility](docs/compatibility.md),
+[the seven design decisions](docs/design.md), and
+[verification](docs/verification.md).
+
+**46 tests and 259 assertions pass on SQLite, PostgreSQL, and MySQL**, with
+zero skips, including the tag-release gates. The full lint/type-check pipeline
+and isolated gem installation also pass.
+
+## Install
+
+Add the gem to your Rails application's Gemfile:
+
+```ruby
+gem "statesman-solid_objects", "~> 0.1.0"
+```
+
+Then run `bundle install`.
+
+For the development version, install from GitHub:
+
+```ruby
+gem "statesman-solid_objects", github: "cardmagic/statesman-solid_objects", branch: "main"
+```
+
+The development bundle uses published dependencies, not sibling checkouts:
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake build
+gem install ./pkg/statesman-solid_objects-0.1.0.gem
+```
+
+For local Rails development, reference this repository:
+
+```ruby
+gem "statesman-solid_objects", path: "../statesman-solid-objects"
+```
+
+Install Solid Objects' tables using its Rails installation instructions. Keep
+your Statesman transition model and table: parent foreign key, `to_state`,
+`sort_key`, `metadata`, `most_recent`, and timestamps. No `from_state` column
+or adapter migration is required. The tested schema uses native JSON metadata,
+nullable `most_recent`, and full unique indexes on parent/sort key and
+parent/most-recent. All participating models must share the same connection
+pool as `ActiveRecord::Base` and Solid Objects.
+
+## Configure
+
+Register the machine in every web and worker process. Use Rails' prepare hook
+so registrations refresh when application classes reload:
+
+```ruby
+Rails.application.config.to_prepare do
+  Statesman::SolidObjects.install
+  Statesman::SolidObjects.register(
+    :orders,
+    parent_class: Order,
+    transition_class: OrderTransition,
+    machine_class: OrderStateMachine,
+    association: :order_transitions,
+    after_commit: :inline
+  )
+
+  Statesman.configure do
+    storage_adapter Statesman::SolidObjects::Adapter
+  end
+end
+```
+
+`install` already selects the adapter; the explicit Statesman block shows the
+standard configuration seam. Registration requires a normal Statesman
+`(parent, options)` constructor. No request-specific objects are registered.
+
+## Authorize explicitly
+
+Installation keeps Solid Objects' default-deny policies. Supply a trusted
+server-side principal and policies for both messages and direct history reads.
+This example authorizes tenant members for the single `orders` registration;
+add application-specific roles and target-state permissions as needed:
+
+```ruby
+policy = lambda do |actor_type:, actor_id:, operation:, arguments:, authorization_context:, **|
+  next false unless authorization_context
+  next false unless actor_type == "statesman-transition"
+
+  identity = JSON.parse(actor_id)
+  next false unless identity.is_a?(Array) && identity.length == 2
+  next false unless identity.first == Order.base_class.name
+
+  arguments = arguments.stringify_keys
+  case operation.to_s
+  when "transition", "initialize_state"
+    next false unless arguments["registration"] == "orders"
+    next false unless arguments["parent_id"].to_s == identity.last
+  when "last", "history"
+  else
+    next false
+  end
+
+  Order.exists?(id: identity.last, tenant_id: authorization_context.tenant_id)
+rescue JSON::ParserError
+  false
+end
+
+SolidObjects.configure do |configuration|
+  configuration.authorize_message = policy
+  configuration.authorize_query = policy
+end
+```
+
+Policies authorize admission, not automatic permission rechecking in a future
+worker. Cross-record `ActiveRecordQueries` scopes still require the
+application's normal tenant scoping.
+
+## Transition
+
+```ruby
+registration = Statesman::SolidObjects.registrations.fetch("orders")
+machine = registration.machine(order, authorization_context: current_user)
+
+machine.transition_to!(:approved, { "source" => "checkout" })
+machine.current_state
+machine.history
+```
+
+A failed bang transition raises `TransitionFailedError` or `GuardFailedError`;
+the non-bang method returns `false`. Guards run again inside the serialized
+commit action and must be pure/repeatable. Use persisted data and string-keyed
+JSON metadata, not unsaved attributes or request-local `Current` values.
+
+To persist the initial transition, pass `initial_transition: true` to
+`registration.machine`. Repeated initialization requests retain one initial
+row; subsequent transitions continue its +10 history.
+
+The inline callback mode runs before/after observers inside the transaction
+and after-commit observers after SQL commit. The 0.14.6 core fix preserves an
+original after-commit exception without failing an already-completed turn.
+
+Choose `after_commit: :effect` during registration for durable, delayed
+callback delivery. Effects may repeat and observe later state; handlers must
+be idempotent, and referenced transition rows must remain available.
+
+Synchronous transitions cannot join an open application transaction. For
+atomic acceptance with application writes, enqueue asynchronously:
+
+```ruby
+Order.transaction do
+  order.update!(label: "submitted")
+  Statesman::SolidObjects::Actor.ref(registration.actor_id(order))
+    .async(authorization_context: current_user)
+    .transition(registration: "orders", parent_id: order.id.to_s,
+      to: "approved", metadata: { "source" => "checkout" })
+end
+```
+
+Execution happens later and cannot roll back already committed caller writes.
+Callbacks must not synchronously nest another transition; enqueue a separate
+authorized message instead. Every transition writer for a parent must use its
+actor.
+
+## Development checks
+
+`bundle exec rake` runs Minitest, Standard, RuboCop, RBS, and Steep.
+SQLite gets a fresh temporary database. For PostgreSQL/MySQL, use a dedicated,
+empty database through `SOLID_OBJECTS_DATABASE_URL`; never use application data.
+See [exact commands and results](docs/verification.md).
+
+On this workstation, pinning the Ruby interpreter avoids a Homebrew launcher
+mismatch:
+
+```sh
+mise exec ruby@3.3.9 -- ruby -S bundle install
+mise exec ruby@3.3.9 -- ruby -rbundler/setup -S rake
+```
+
+`SOLID_OBJECTS_PATH` is an optional development override. It is unset during
+release-dependency verification.
+
+## Releases
+
+Pushing a matching version tag such as `v0.1.0` runs all CI checks, publishes
+the gem through RubyGems trusted publishing, and creates a GitHub Release.
+Ordinary commits do not publish. See [release setup and steps](docs/releases.md),
+including the pending publisher's expiration before the first release.

data/docs/compatibility.md

@@ -0,0 +1,92 @@
+# Compatibility boundary
+
+This is a registered-machine adapter, not transparent transport of a live
+Statesman observer. It uses the published Statesman 13.3 API and Solid Objects
+0.14.6. Every process must register the same classes and association names.
+
+## Adapter contract
+
+The six requested methods are implemented: initialize, create, last, history,
+reset, and private next_sort_key. The Minitest contract test exercises their
+return values, empty history, metadata, +10 keys, reload behavior, and reads
+after an association has already loaded. Before/after/after-commit order is
+covered with real database callbacks and fresh-process workers.
+
+Upstream exposes [RSpec adapter shared examples](https://github.com/gocardless/statesman/blob/3a7e9b7a69a6d627e8e76e84e5c59cd0827755c8/spec/statesman/adapters/shared_examples.rb).
+They were inspected and their compatible behavior covered in Minitest, but
+they do **not** run unchanged:
+
+| Upstream expectation | This adapter |
+| --- | --- |
+| Supplied transition class and parent accessors | Preserved |
+| Persisted transition returned by create | Preserved |
+| Metadata, +10 sort keys, chronological history | Preserved |
+| last with force_reload and observer ordering | Preserved on the reconstructed machine |
+| Calls to the original supplied observer instance | Intentionally not preserved |
+| Repeated raw create from x to y regardless of current graph state | Rejected when no longer a valid transition |
+
+Direct adapter calls still require an explicit boot registration. The
+authoritative worker check deliberately makes create a validated command,
+not an unconditional row append. Claiming an unchanged upstream shared-suite
+pass would be inaccurate.
+
+## Supported and tested
+
+- Persisted parents and named initial states.
+- Normal Statesman constructors with explicit transition association.
+- Initial transition creation, idempotent repeated initialization, and continued history.
+- Native JSON transition metadata with string keys.
+- A stock transition table without an additional from_state column.
+- Nullable most_recent with full unique indexes on parent/flag and parent/sort key.
+- ActiveRecordQueries state scopes and uncached last/history reads.
+- Six concurrent single-use and guarded self-transitions, with domain rejection.
+- Atomic same-pool database callback writes, including rollback on failure.
+- Inline callback exceptions after successful commit, including unrelated application rejections.
+- Delayed effect delivery, independent retries, duplicate delivery, and fresh workers.
+- Denied absent/cross-tenant principals, unchanged default-deny installation.
+- Published-gem loading outside the workspace.
+
+## Restrictions applications must accept
+
+Guards execute in the caller and again in the serialized action. They must be
+pure/repeatable and depend on persisted data and explicit JSON inputs.
+Unsaved attributes, request Current values, original guard callback objects,
+and custom observer instance state do not cross the mailbox boundary.
+Symbol-key-only guards fail after JSON normalization; use string keys.
+
+Both pre-commit and post-commit callback nesting are rejected: one actor
+command may persist one transition. Enqueue a new authorized command for
+follow-up work. Before/after callbacks must contain bounded database work
+using the shared pool, not external I/O.
+
+Inline callbacks are not durable jobs. A separate waiter can observe committed
+completion before its worker's callback finishes or fails. Emitted callbacks
+are delayed and at least once, may see later state, and need idempotency.
+Keep referenced transition rows until effects finish.
+
+Sync calls cannot join an ambient application transaction. Async acceptance
+can commit with caller writes, but later execution cannot undo those writes.
+All transition writers and coordinated guard data must obey the application's
+ownership rules; arbitrary bypass writes are not serialized by this adapter.
+
+Registration currently validates shared pools at registration time. Do not
+change connection routing after registration; sharded or separately pooled
+models are not supported. Refresh registrations after Rails class reloads.
+
+## Not certified for 0.1.0
+
+- Failure callback cardinality/side effects: worker validation and caller
+  handling can both invoke Statesman failure callbacks; worker database writes
+  in a rejected turn roll back. Do not rely on exactly-once failure callbacks.
+- Custom machine constructors, overridden transition methods, polymorphic
+  association layouts, composite keys, class renames, and sharding.
+- Non-null/partial-index transition schema variants, serialized-text metadata,
+  or Statesman's cached-current-state-column extension.
+- Populating an optional existing from_state column. The adapter does not need
+  it and currently leaves it untouched.
+- Multiple Rails versions, production load, abrupt process death, stale-lease
+  takeover, retention/migration workflows, and supervisor CLI deployment.
+
+A published 0.1.0 should retain these boundaries unless additional tests and
+implementation explicitly change them. This local candidate has not been
+published or presented as universally drop-in compatible.

data/docs/core-follow-up-prompt.md

@@ -0,0 +1,148 @@
+# Fresh Codex session prompt
+
+Historical handoff: the concrete bug was fixed and released in Solid Objects
+0.14.6 on September 12. Do not use this prompt as an outstanding task.
+
+Fix Solid Objects' handling of errors raised **after a fenced actor turn has
+already committed**. A Statesman integration prototype demonstrated this
+specific bug using existing primitives. Do not start by adding caller-bound
+execution, arbitrary Ruby-object transport, a new event API, or synchronous
+joining of ambient Active Record transactions.
+
+## Repositories and scope
+
+Work in `~/Sites/solid_objects/solid-objects-ruby/`. Read
+`~/Sites/solid_objects/AGENTS.md`, the repository's `AGENTS.md`, and the TDD
+skill at `~/.claude/skills/tdd/SKILL.md` before changing code. Follow the
+workspace's applicable skills and preserve all existing edits. Use the repo's
+Minitest workflow for TDD. Proceed through the scoped red/green cycle without
+per-test approval; stop if a materially broader API decision is needed.
+
+Read the sibling prototype's `docs/findings.md`, `docs/design.md`,
+`test/prototype_test.rb`, and `lib/statesman/solid_objects/execution.rb` in
+`~/Sites/solid_objects/statesman-solid-objects/`. The prototype currently uses
+core 0.14.5 at `e7b7ab7634cd2980de277fcfa9217d93c9c3aa52`; verify the current
+checkout rather than assuming it still has the bug.
+
+Keep Statesman a dependency of the standalone adapter only. Do not add it to
+core, patch Statesman, publish a release, push commits/tags, deploy, or open a
+PR. You may update the sibling's specific regression expectation after the
+core fix, but do not expand this into finishing/publishing the adapter.
+
+## What the prototype already proves
+
+Using only an actor mailbox, a registered commit action, Active Record
+transaction callbacks, and emitted effects:
+
+- A registered machine can be rebuilt from persisted data in a fresh worker.
+- Six racing transitions yield one success and five domain rejections, versus
+  five storage conflicts with the stock Active Record adapter.
+- Before/after database callbacks commit or roll back with actor state.
+- Existing Rails transaction callbacks provide inline after-commit timing.
+- Existing effects provide deferred, retryable callback delivery.
+- Existing async enqueue commits/rolls back with application writes, while
+  actual execution occurs later.
+
+Do not reframe these working capabilities as missing core APIs. The prototype
+passes 28 scenarios on SQLite, PostgreSQL, and MySQL; some are characterization
+tests for restrictions and the bug, not evidence of full Statesman parity.
+
+## Reproduce the bug independently of Statesman
+
+Inspect `Executor#call`, `Executor#complete`, `fail_message`,
+`matching_claim!`, `Lease#fenced_transaction`, and activation/synchronous
+invocation cleanup. Also read `docs/correctness.md`, `docs/architecture.md`,
+and the commit-action/effect documentation.
+
+A commit action registers a Rails after-commit callback. SQL commits actor
+state, application rows, and message completion, and deletes the claim. The
+callback then raises. Executor treats it as a pre-commit failure and tries to
+fail a message whose claim is already gone. The original exception is masked
+as `SolidObjects::LostActivation: message claim changed`.
+
+The sibling test named "an inline after-commit exception is masked as lost
+activation after persistence" demonstrates this. It currently asserts the
+bug to keep the characterization suite green. The message stays completed
+and a subsequent transition succeeds; do not claim observed durable data
+corruption.
+
+Write a focused core regression FIRST, using a normal test Active Record
+model callback or transaction callback inside a registered commit action.
+No Statesman dependency or mocks bypassing real transaction/cleanup behavior.
+Watch it fail for this exact reason before implementing a fix.
+
+## Required semantics
+
+Design the smallest fix and make the boundary explicit:
+
+1. Distinguish a transaction that rolled back from one that committed before
+   a callback or post-commit reporting step raised. Do not infer commitment
+   merely from reaching the end of the transaction block before SQL commit.
+2. A committed turn must not enter the pre-commit rejection/failure path,
+   restore its old actor snapshot, requeue its business action, create a false
+   dead letter, or report missing claim ownership as the callback error.
+3. Preserve a truthful completed message/result and committed state. A
+   callback error cannot retroactively roll back those writes.
+4. Preserve useful original exception class, message, and cause/backtrace.
+   A process executing the failing callback must expose that failure through
+   an explicit error/reporting path. Decide and document whether its direct
+   caller receives the original error or a dedicated post-commit error.
+5. A separate waiter may already have observed completion before the worker
+   callback fails. Do not promise identical exception delivery to every
+   caller or add distributed acknowledgement machinery to pretend otherwise.
+   Provide or reuse an observable worker diagnostic without relabeling the
+   committed message as a failed actor turn.
+6. Leave the activation either consistent with committed state or safely
+   discarded/reloaded. Preserve lease/claim cleanup and later mailbox progress.
+7. Pre-commit callback failures/rejections must still roll back and follow
+   the existing retry/rejection policy. Effects retain their independent
+   at-least-once delivery behavior; do not introduce exactly-once claims.
+
+Determine whether post-commit `Rejected` or `LostActivation` exceptions need
+the same phase-aware handling rather than letting exception class override
+the already-committed fact. Avoid rescuing and silently swallowing all errors.
+
+## Validation
+
+Test successful callbacks, failure before commit, failure after commit,
+committed application/actor/message state, no replay or false dead letter,
+accurate diagnostics, and the next message on the same actor. Cover caller
+assistance and a real separate worker with a waiting caller. Use barriers/
+pipes rather than timing sleeps, and verify the runtime's actual load path.
+
+After the fix, temporarily revert only the fix and show that the regression
+fails again for the original reason. Restore it and run the full core
+`bundle exec rake` and dedicated-database PostgreSQL/MySQL tests using
+`SOLID_OBJECTS_DATABASE_URL`. Never point the harness at application data.
+Use Ruby 3.3.9 explicitly if the Homebrew launcher selects Ruby 4.
+
+Run the sibling prototype again, changing only the known-bug assertion to the
+documented new contract. Its ordinary transitions, concurrency negative
+control, effect retries, and async transaction examples must remain valid.
+
+Assess parity scope before editing JS: a Rails transaction callback surface
+is Rails-only; a shared executor correctness change may need an equivalent
+JS fix and the workspace parity workflow. Follow that distinction rather
+than adding a Statesman port or reflexively editing both runtimes.
+
+Update relevant correctness/error-boundary documentation and CHANGELOG.
+Update roadmap/parity only as required by applicable repo/workspace rules.
+Owned Ruby files must start with `# rbs_inline: enabled` and use `# @rbs`
+annotations; no explanatory inline source comments. Put reasoning in docs
+and the handoff.
+
+## Explicitly deferred decisions
+
+Preserving the caller's original observer, unsaved attributes, and ambient
+`Current`, or making transition execution join an outer transaction, are
+separate compatibility/product requirements. The existing-primitives
+prototype does not establish a need for either. Do not implement them here.
+
+String/symbol metadata normalization, extra transition schema fields, initial
+transitions, custom machine factories, nested transitions, and failure-callback
+compatibility belong to the standalone adapter's release work unless an
+independent core regression demonstrates otherwise.
+
+Finish with the cause, chosen post-commit semantics, changed files, actual
+red/green and database results, parity assessment, and remaining restrictions.
+Do not call the standalone gem fully compatible or released.

data/docs/design.md

@@ -0,0 +1,139 @@
+# Design: existing-primitives Statesman integration
+
+Status: unpublished 0.1.0 registered-machine adapter, not full drop-in compatibility. Decisions were
+outlined in [the experiment plan](prototype-plan.md) before implementation;
+this document records the resulting design and evidence. It supersedes the
+earlier conclusion that original-observer transport blocks any integration.
+
+## 1. Transitions stay in Active Record
+
+Keep the transitions table and Rails model/query surfaces. The actor handler
+only reads application records and stages intents. A boot-registered
+`commit_action` reloads the parent, constructs its registered state machine,
+revalidates the transition and guards, invokes before/after observers, and
+writes the transition. Those writes and actor state commit together.
+
+The authoritative check belongs in this serialized action, not only in the
+caller's `Machine#transition_to!`. When it was removed experimentally, both
+single-use-transition and guarded-self-transition races admitted all six
+callers. With it present, each admitted one caller and rejected five.
+
+The caller's observer is not serialized. A worker-local execution context
+routes the reconstructed machine's adapter back into the current commit
+action without recursively sending another actor message. It is scoped with
+`ensure`, restricted to the matching registration and parent, and not a
+request-local registry pretending to be durable transport.
+
+The adapter uses the stock transition schema. The actor captures the source
+state in the emitted effect arguments, so delayed callbacks need no extra
+`from_state` column. This relies on the same sole-writer premise as the counter.
+
+## 2. Reads go directly to the transitions table
+
+`last` and `history` use uncached Active Record queries ordered by `sort_key`.
+They do not enqueue actor queries. The actor is the sole transition writer,
+so committed table rows are the useful public read model.
+
+Both read methods call the application's `authorize_query` policy, except
+inside the matching, already-admitted worker execution. Both callback modes
+can read that machine's state. Reads are current at the database query, not
+linearizable mailbox barriers relative to work still queued. `force_reload`
+has no extra effect because these methods do not cache. `reset` is a no-op.
+Cross-record `ActiveRecordQueries` scopes remain ordinary application queries
+and need the application's usual tenant scoping.
+
+## 3. Keep most_recent, remove contention workarounds
+
+Keep `most_recent` and normal uniqueness protection for query compatibility.
+Clear the old true row before inserting the new true row, inside the same
+transaction. Use `nil` for nullable columns and `false` for non-nullable ones.
+The tested schema uses a nullable column and a full unique index on parent
+and `most_recent`, portable across the three databases.
+
+There is no MySQL temporary write of a new row's flag, partial-index check,
+`requires_new` transaction, or Statesman conflict retry loop in this adapter.
+The mailbox removes competing transition writers, not the need to maintain
+the query marker. Core still uses its own SQL locks/fencing and retry policy.
+Other writers bypassing the actor invalidate the premise.
+
+## 4. Persist +10 sort keys in actor state
+
+The actor stores counters keyed by transition association. On first use, seed
+from that association's highest existing `sort_key`; then increment by ten.
+Different registrations sharing the same history share its counter. Failed
+or rejected commit actions roll back the counter as well as application writes.
+
+Initial-transition creation is a separate mailbox operation. It returns an
+existing first transition when history already exists; otherwise it persists
+the named initial state without demanding a self-transition in the graph.
+
+Fresh OS-process workers produced keys 10 and 20 and ordered history after
+restart. No actor eviction/restart resets the durable counter. External table
+imports, deleting actor state, and mixing actor/non-actor writers require a
+separate migration or recovery procedure; they are not supported workflows.
+
+## 5. Offer two explicit after_commit boundaries
+
+Inline mode uses Statesman's `ActiveRecordAfterCommitWrap` through
+`add_transaction_record` on the connection executing the fenced turn. The
+observer runs after SQL commit: measured transaction depths were 1 for
+before/after and 0 for after_commit. It runs on the reconstructed machine,
+not the original caller object. It is not a durable callback queue, and a
+remote caller's receipt of completion need not wait for that worker callback.
+
+Effect mode stages `emit(:statesman_after_commit, ...)` in the actor handler.
+The outbox entry commits with the transition. An effect worker reconstructs
+the machine and exact transition row later. Tests prove fresh-process
+delivery, independent retries, repeated side effects, and observation of
+later transition history. Handlers must be idempotent. Transition rows must
+remain available until effects finish.
+
+Neither mode permits callbacks to reuse a transition write, including before/
+after callbacks while the transaction is open. A single-use write guard rejects
+re-entry clearly; failures inside the transaction roll back the original write.
+Follow-up transitions need a separate authorized actor message.
+
+Core 0.14.6 fixes the demonstrated post-commit exception masking, and is now
+the minimum dependency. Tests verify the original RuntimeError and unrelated
+application Rejected exceptions while the transition remains committed. The
+adapter translates only its recognized validation rejection codes.
+
+## 6. One actor per persisted parent
+
+The actor type is `statesman-transition`; its ID is a JSON tuple of the
+parent's base-class name and scalar primary key converted to a string.
+`Order(42)` and `Invoice(42)` have different identities. STI subclasses share
+their base table's record identity. Association counters allow multiple
+machines on that parent without multiple independent writers.
+
+Boot registrations map trusted names to model/machine classes. Messages carry
+registration name, parent ID, target state, and JSON metadata, not class names
+to constantize. The actor verifies that the resolved parent matches its own
+ID. Missing registration, mismatched transition classes, and unsaved/wrong-class
+parents fail clearly. Composite keys, sharding, and class renames are outside
+the tested identity contract. The same-pool registration check deliberately
+rejects separate pools even if their URLs identify the same database.
+
+## 7. Explicit default-deny authorization
+
+Installation does not replace core's denying policies. The application must
+provide `authorize_message` and `authorize_query` and pass a trusted principal
+to public calls. The example policy binds permissions to parent class, parent
+ID, tenant, and allowed operations. More complex applications must also check
+the registration/transition permissions in message arguments.
+
+The internal execution context only allows matching reads and fenced commit
+writes for previously admitted work. It does not reconstruct the caller's
+principal or silently forward `Current`. Worker-time revocation checks, when
+required, belong in explicit persisted business policy. Tests deny missing
+principals and cross-tenant reads/writes before actor creation.
+
+## Compatibility boundary
+
+This design trades original-object identity and ambient transaction semantics
+for durable, independently executable commands. That is useful integration,
+but not the entire upstream adapter contract. Repeated guards, JSON metadata,
+failure callback behavior, and callback identity restrictions are listed in
+[compatibility](compatibility.md). Historical prototype findings remain in
+[the dated investigation](findings.md); current results are in
+[verification](verification.md).