statesman-solid_objects 0.1.0

data/docs/findings.md

@@ -0,0 +1,197 @@
+# Findings: what actually needs to change?
+
+Historical investigation from September 11. Core 0.14.6 subsequently fixed the
+post-commit bug, and the adapter now uses published dependencies without the
+extra transition column. See [current compatibility](compatibility.md) and
+[current verification](verification.md); the counts and limitations below
+describe the original prototype, not the current release candidate.
+
+Measured on September 11, 2026. **Existing primitives support a useful
+Statesman integration. A caller-bound execution API and synchronous joining
+of application transactions are not prerequisites.**
+
+This corrects the earlier observer-transport conclusion. Original Ruby object
+identity cannot cross a durable JSON message boundary, but registered machine
+classes and persisted parent records can reconstruct the required behavior.
+That distinction is the basis of this prototype.
+
+## Concurrency result
+
+Six threads hold separate Active Record connections. A queue barrier stops
+them after they have read the original state and entered caller-side guard
+validation, then releases all six. These are real Statesman calls, not mocked
+adapter calls or sequential requests.
+
+| Scenario | Successes | Other outcomes |
+| --- | ---: | --- |
+| Prototype, bang single-use transition | 1 | 5 `TransitionFailedError` |
+| Prototype, non-bang single-use transition | 1 | 5 `false` |
+| Prototype, guarded self-transition | 1 | 5 `GuardFailedError` |
+| Stock Active Record adapter, same single-use race | 1 | 5 `TransitionConflictError` |
+
+The guarded self-transition consumes one persisted unit. It demonstrates why
+checking only the source state would be insufficient.
+
+The actor stages a commit action, and that action reconstructs the machine
+and repeats validation before writing. Statesman also validates before
+calling the storage adapter, so merely serializing adapter inserts would
+leave stale caller decisions intact. See upstream
+[`Machine#transition_to!`](https://github.com/gocardless/statesman/blob/3a7e9b7a69a6d627e8e76e84e5c59cd0827755c8/lib/statesman/machine.rb)
+and the [Active Record adapter](https://github.com/gocardless/statesman/blob/3a7e9b7a69a6d627e8e76e84e5c59cd0827755c8/lib/statesman/adapters/active_record.rb).
+
+Negative control: temporarily replacing the worker's `transition_to!` call
+with a direct persistence call made **both concurrency tests fail with six
+successes**. The authoritative validation was then restored. This test proves
+the particular concurrency guarantee, not universal absence of SQL errors or
+conflicts when application code bypasses the actor.
+
+## Restrictions that matter
+
+| Capability or restriction | Observed behavior | Practical significance |
+| --- | --- | --- |
+| Registered machine reconstruction | Works in fresh actor/effect processes booted before enqueue | Existing primitives suffice; no per-request closure registry |
+| Before/after database callbacks | Run around the row write inside the fenced transaction; failures roll everything back | Suitable for bounded same-pool database work |
+| Inline after-commit timing | Runs after commit; transaction depth is zero | Existing Rails callback registration is enough for timing |
+| Inline after-commit error | Originally became `LostActivation` despite successful persistence; the local core fix exposes the original `RuntimeError` | Persistence remains committed; report the callback failure in the executing process |
+| Emitted callbacks | Deferred, retryable, can duplicate and observe later history | Use for idempotent eventual work, not identical inline semantics |
+| Application transactions | Async enqueue commits/rolls back with application writes; sync rejects before enqueue | Existing async API solves atomic acceptance, not atomic execution |
+| Original observer and unsaved parent | Worker uses new objects and persisted attributes | Material if callbacks depend on instance identity or unsaved data |
+| Request-local `Current` | Visible with caller assistance, absent in a fresh worker | Pass explicit JSON data or persist context; local success can mislead |
+| Guard evaluation | Caller and worker both evaluate guards | Guards must be pure/repeatable; worker's persisted view is authoritative |
+| Metadata | Symbol keys become strings through JSON | Normalize at the adapter/app boundary; not a reason for arbitrary Ruby serialization |
+| Callback errors before commit | Surface as `SolidObjects::MessageFailed` with original class in details | Exception identity changes; application retry handling needs review |
+| Guard error details | Error retains caller parent but not original guard callback object | Class-level compatibility, not full exception-object identity |
+| Connection pools | Registration rejects a different pool before enqueue | Same URL through separate pools is not sufficient |
+| Nested callback transitions | Emitted callback cannot reuse the commit-only write path | Requires a new authorized actor message; nesting is not drop-in |
+| History and state scopes | Sorted rows, +10 keys, most-recent flags and `in_state` work after restart | Preserve the useful Rails query surface |
+
+An async command that fails later does **not** roll back application writes
+that already committed with its enqueue. Likewise, effects cannot make remote
+side effects part of a SQL rollback. These are different product contracts,
+not missing event APIs.
+
+The callback retry test deliberately writes an event and then raises: the
+event is written twice across two effect attempts, while the transition row
+is written once. This is a deterministic demonstration of duplicate delivery,
+not a process-crash experiment.
+
+## The demonstrated core bug
+
+The original inline callback characterization raised
+`RuntimeError, "failed after_commit"` after SQL commit. Unfixed core then did
+the following:
+
+1. `Executor#complete` has already saved actor state, transition rows, and
+   message completion, and deleted the claimed-message row.
+2. The Rails after-commit callback raises while the transaction method returns.
+3. `Executor#call` catches the error as though the actor turn had failed,
+   restores its old in-memory snapshot, and calls `fail_message`.
+4. `matching_claim!` cannot find the already-deleted claim and raises
+   `LostActivation, "message claim changed"`.
+
+The test observes a completed message with no message error, the committed
+transition, no dead letter, and a successful subsequent transition. It does
+**not** demonstrate durable-state corruption. It does demonstrate misleading
+failure classification and lost top-level callback diagnostics.
+
+Reproduction in the prototype:
+
+```sh
+mise exec ruby@3.3.9 -- ruby -rbundler/setup -Itest test/prototype_test.rb \
+  --include /inline_after.commit_exception/
+```
+
+The local core fix was developed against an independent failing Minitest
+regression using Active Record callbacks without Statesman. The prototype
+test now expects the original `RuntimeError, "failed after_commit"`, retaining
+its persistence and subsequent-transition assertions. A separate waiting
+caller may receive the completed result before a worker callback fails; the
+error is exposed in the executing process without rewriting message history.
+The [fresh-session prompt](core-follow-up-prompt.md) records the original scope.
+
+## What is not claimed
+
+- This does not pass the full upstream adapter contract. Upstream
+  [shared examples](https://github.com/gocardless/statesman/blob/3a7e9b7a69a6d627e8e76e84e5c59cd0827755c8/spec/statesman/adapters/shared_examples.rb)
+  expect the supplied observer itself to receive callbacks and permit repeated
+  raw `create(:x, :y)` calls. This prototype reconstructs the machine and
+  validates commands. It exposes all six requested methods but does not run
+  those RSpec examples unchanged.
+- Initial transition creation, arbitrary custom machine constructors,
+  failure-callback cardinality/side effects, nested before/after transitions,
+  non-null/partial-index schema variants, multiple Rails versions, composite
+  keys, and sharding are not certified.
+- Stock transition tables do not necessarily contain the prototype's extra
+  `from_state` column. Removing that schema requirement or shipping a migration
+  is adapter release work. Boot registration validation and a public factory/
+  async helper also need release polish.
+- The code assumes one actor owns every transition writer for a parent.
+  Guarded application data changed by other writers still needs appropriate
+  application-level coordination.
+- Fresh-process tests use real `SolidObjects::Worker` and `EffectExecutor`
+  instances. They do not exercise the supervisor CLI, host Rails autoloading,
+  abrupt worker death, stale-lease takeover, deployment upgrades, production
+  throughput, or multi-tenant revocation after enqueue.
+- Steep checks the library with the same lenient diagnostic policy used by
+  core and shared framework signatures. Numerous Rails/Statesman boundaries
+  remain `untyped`; a green type check is not complete static verification.
+- No gem publication, release, deployment, or upstream PR. The subsequent core
+  fix and JS parity documentation remain local and uncommitted.
+
+## Verification
+
+The original characterization matrix, before the core fix:
+
+| Database | Tests | Assertions | Failures / errors / skips | Elapsed |
+| --- | ---: | ---: | --- | ---: |
+| SQLite | 28 | 136 | 0 / 0 / 0 | 3.21 s |
+| PostgreSQL 18 container | 28 | 136 | 0 / 0 / 0 | 6.03 s |
+| MySQL 8.4 container | 28 | 136 | 0 / 0 / 0 | 6.32 s |
+
+These are single final matrix runs, not a load benchmark. The SQLite default
+task additionally passed Standard, RuboCop (13 files), RBS generation/
+validation, and Steep. RBS reports zero generated files when existing
+signatures already match its output.
+
+Runtime: Ruby 3.3.9, Active Record 8.1.3.1, Solid Objects 0.14.5 at
+`e7b7ab7634cd2980de277fcfa9217d93c9c3aa52`, and Statesman 13.3.0 at
+`3a7e9b7a69a6d627e8e76e84e5c59cd0827755c8`. Dependencies are pinned in
+`Gemfile.lock`. Commands are in the [README](../README.md).
+
+The disposable database containers were removed after verification. To create
+equivalent local-only test services again (no production credentials):
+
+```sh
+docker run --detach --name statesman-prototype-pg-20260911 \
+  --publish 127.0.0.1:55439:5432 \
+  --env POSTGRES_HOST_AUTH_METHOD=trust --env POSTGRES_DB=statesman_prototype \
+  postgres:18-alpine
+docker run --detach --name statesman-prototype-mysql-20260911 \
+  --publish 127.0.0.1:53309:3306 \
+  --env MYSQL_ALLOW_EMPTY_PASSWORD=yes --env MYSQL_DATABASE=statesman_prototype \
+  mysql:8.4
+```
+
+Wait for each database to finish initialization before running its suite.
+The connection pool is explicitly 20 because six callers wait at a barrier
+while holding separate connections; the default pool of five cannot satisfy
+that test's setup. These unauthenticated containers are disposable local
+fixtures, not deployment recommendations.
+
+The September 12 core-fix follow-up reran the prototype against the locally
+edited core on Ruby 3.3.9 and Active Record 8.1.3.1: SQLite, PostgreSQL 18,
+and MySQL 8.4 each passed 28 tests and 136 assertions with no failures, errors,
+or skips. The SQLite default pipeline also passed Standard, RuboCop, RBS, and
+Steep. The inline callback test now asserts the original `RuntimeError`;
+its committed-history and subsequent-transition assertions are unchanged.
+
+TDD began with the normal-transition test failing on the unimplemented
+adapter. Subsequent red/green tests drove effect mode, connection-pool
+validation, shared association counters, authorized callback reads, and the
+nested-write boundary. The deliberate validation-removal experiment supplied
+the final negative control.
+
+The older [observer-boundary probe](../experiments/observer_boundary_probe.rb)
+remains historical evidence of what cannot be transported, not a release gate
+or proof that reconstruction is impossible. It is excluded from the default
+suite and depends on core's internal test harness.

data/docs/prototype-plan.md

@@ -0,0 +1,47 @@
+# Existing-primitives experiment
+
+The earlier observer transport probes tested a stronger compatibility goal
+than a useful Statesman integration necessarily needs. This experiment keeps
+Solid Objects core unchanged and tests registered, reconstructible machines.
+
+## Decisions before implementation
+
+1. Keep the existing Active Record transitions table. A boot-registered commit
+   action reloads the parent and machine, performs authoritative Statesman
+   validation, runs before/after callbacks, and writes the transition.
+2. Read history directly from the table, ordered by sort key. Authorize public
+   reads; reads inside an already-authorized matching commit action use its
+   narrowly scoped execution context.
+3. Keep `most_recent`. Clear the previous row and insert the next row in the
+   same transaction, using the column's nullability for old-row values.
+4. Keep +10 sort keys in actor state, seeded from existing table history.
+   Rejected commit actions must roll back the actor counter and table writes.
+5. Compare two callback modes: normal transaction-record after-commit callbacks,
+   and delayed callbacks reconstructed from an emitted effect. Measure failures
+   and duplicate delivery rather than assuming they are interchangeable.
+6. Use a JSON tuple of parent base-class name and scalar primary key as actor
+   identity, with separate counters per transition association inside that actor.
+7. Keep default-deny public policies. Pass an authenticated principal to public
+   calls and bind policy checks to actor identity and operation. Registrations
+   exist at boot in every process; no request-specific closures are transported.
+
+## Behavioral experiment list
+
+- A normal transition persists and runs callbacks around the table write.
+- Concurrent attempts at a single-use transition have one winner; compare the
+  same race with Statesman's Active Record adapter.
+- Guarded self-transitions recheck persisted conditions in the serialized turn.
+- History, query scopes, and sort keys survive fresh-process execution.
+- A boot-registered machine works in a separate worker without caller objects.
+- Unsaved parent attributes, request-local context, and observer instance state
+  reveal the actual reconstruction restrictions.
+- Callback database writes roll back with rejected or failed turns.
+- Inline after-commit failure is observed after durable commit.
+- Emitted callbacks survive restart and retry independently of transition state.
+- Existing application transactions reject sync; async enqueue commits or
+  rolls back with the surrounding application transaction and runs afterward.
+- Authorization and mismatched database pools fail clearly.
+
+The final findings and revised core prompt will distinguish necessary fixes,
+optional compatibility work, and behavior already supported. This is a
+prototype, not a published 0.1.0 gem or a claim of complete adapter parity.

data/docs/release-plan.md

@@ -0,0 +1,21 @@
+# 0.1.0 continuation
+
+The 0.14.6 core release removes the demonstrated post-commit blocker. Keep
+core and JS untouched and continue the registered-machine design, using the
+published gems by default rather than a sibling checkout.
+
+TDD scenarios, in order:
+
+1. The standalone package declares its name, version, and released runtime dependencies.
+2. Inline and emitted callbacks work with the stock transition schema, without `from_state`.
+3. Public registration builds an authorized machine; missing/mismatched registration and parents fail clearly.
+4. Initial transitions persist once and continue normal +10 history.
+5. Callback nesting cannot reuse an already-consumed transition write.
+6. Adapter contract behavior, including metadata and history reloads, has explicit tests and documented differences from upstream shared examples.
+7. Installation leaves authorization denied unless the application provides policies.
+8. The gem loads outside this workspace and the complete suite passes against the released core on all three databases.
+
+Reconstruction still does not preserve the original observer, unsaved parent
+attributes, request-local state, or ambient synchronous transactions. Those
+are documented restrictions, not new core feature requests. Do not publish or
+claim full drop-in compatibility during this continuation.

data/docs/releases.md

@@ -0,0 +1,67 @@
+# Tag releases
+
+GitHub Actions runs `.github/workflows/ci.yml` on pushes, pull requests, and
+manual requests. SQLite runs the full Minitest, Standard, RuboCop, RBS, and
+Steep pipeline plus a gem build. PostgreSQL 18 and MySQL 8.4 run the tests
+against disposable service databases.
+
+Only a `v*` tag pushed to `cardmagic/statesman-solid_objects` can run the
+release job. That job waits for all three checks, verifies that the tag
+equals `v` plus `Statesman::SolidObjects::VERSION`, and builds the gem before
+requesting publishing credentials. It pushes the exact built artifact to
+RubyGems.org and creates a GitHub Release with that gem attached.
+
+Ordinary pushes, pull requests, fork workflows, and manual workflow requests
+do not publish. The release job alone has `id-token: write` and
+`contents: write`; test jobs have read-only repository access. Actions are
+pinned to commit SHAs, and checkouts do not retain Git credentials.
+
+## Trusted publisher
+
+RubyGems uses the following identity:
+
+| Setting | Value |
+| --- | --- |
+| Gem | `statesman-solid_objects` |
+| Repository owner | `cardmagic` |
+| Repository name | `statesman-solid_objects` |
+| Workflow filename | `ci.yml` |
+| Environment | `release` |
+
+The GitHub `release` environment permits only tags matching `v*`, with no
+manual approval required. RubyGems trusts that environment and workflow via
+OIDC; no long-lived RubyGems API key is stored in GitHub.
+
+Before the first release, configure a
+[pending trusted publisher](https://rubygems.org/profile/oidc/pending_trusted_publishers)
+with the values above. Leave the reusable-workflow repository fields blank.
+The pending publisher created during setup was valid for about 12 hours.
+Check its expiration before the first tag and recreate it if necessary.
+The first successful push converts it into the gem's regular trusted
+publisher. Subsequent releases use the same workflow without repeating setup.
+See the [RubyGems trusted-publishing guide](https://guides.rubygems.org/trusted-publishing/).
+
+## Publish a version
+
+1. Update `lib/statesman/solid_objects/version.rb`, date the matching
+   `CHANGELOG.md` entry, and update the README's release status. Regenerate
+   `Gemfile.lock` with Bundler and update version-specific package tests.
+2. Run `bundle exec rake` and `bundle exec rake build`.
+3. Commit and push `main`; wait for all CI checks to pass.
+4. Push an annotated tag matching the version. For the first release:
+
+   ```sh
+   git tag -a v0.1.0 -m "Version 0.1.0"
+   git push origin v0.1.0
+   ```
+
+5. Watch that tag's CI run. Verify the RubyGems version, GitHub Release, and
+   attached artifact before announcing publication.
+
+Configuring this pipeline does not publish a gem. Its first OIDC exchange
+and upload can only be validated end to end by an actual release.
+
+If the RubyGems upload succeeds but GitHub Release creation fails, the gem is
+already published. Check both services before retrying; RubyGems versions
+cannot be overwritten. Finish the missing GitHub Release instead of pushing
+the same gem again.

data/docs/verification.md

@@ -0,0 +1,103 @@
+# Verification
+
+September 12, 2026 continuation, after Solid Objects 0.14.6 was published.
+
+The dependency lockfile now resolves released `solid_objects 0.14.6` and
+`statesman 13.3.0` from RubyGems. No sibling core checkout is required for
+runtime, tests, RBS, or Steep. Ruby is 3.3.9 and Active Record is 8.1.3.1.
+
+## Database evidence
+
+The final 41-scenario run passed with 217 assertions and zero failures, errors, or
+skips on each database:
+
+| Database | Elapsed |
+| --- | ---: |
+| SQLite | 3.94 s |
+| PostgreSQL 18 | 7.04 s |
+| MySQL 8.4 | 7.66 s |
+
+The SQLite default task also passed Standard, RuboCop (17 files), RBS
+generation/validation, and Steep. Steep uses the installed core's signatures
+and its lenient diagnostic policy; Rails/Statesman boundaries still include
+untyped values.
+
+A package test included in that matrix builds the gem, installs it into a temporary gem
+home, and starts an unbundled Ruby process outside the workspace. It verifies
+that the installed adapter and released core load, without the repository's
+load path. The standalone `rake build` task also produced the local 0.1.0 artifact.
+The README authorization example was executed against the real adapter for
+both initial and ordinary transitions, including keyword-argument normalization.
+
+These are integration checks, not throughput measurements or a complete Rails
+version matrix. See [compatibility](compatibility.md) for remaining boundaries.
+
+## TDD evidence
+
+Observed red/green failures during this continuation:
+
+- Missing standalone gemspec -> valid package name/version/dependencies.
+- Missing default require entrypoint -> successful gem loading.
+- Stock schema -> MessageFailed while the old adapter tried writing from_state;
+  removing that write and putting the source state in effect arguments fixed both modes.
+- Public factory keyword rejected -> authorized registered-machine construction.
+- Invalid callback mode accepted -> explicit configuration validation.
+- Missing registration silently defaulted to orders -> required matching registration.
+- Initial transition rejected as pending-to-pending -> distinct idempotent initialization command.
+- Recursive before callback raised SystemStackError -> clear re-entry error and rollback.
+- Application post-commit rejection became KeyError -> preserve unrecognized rejection codes.
+
+The race negative control was repeated against the released dependencies:
+temporarily replacing the worker's transition_to! with direct persistence made
+both the single-use and guarded-self-transition tests fail with six successes.
+Restoring validation made both pass again. The continuing suite also retains
+the same stock Active Record comparison.
+
+## Reproduce
+
+With the correct Ruby environment:
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake build
+```
+
+On this workstation, the Homebrew bundle launcher can select the wrong Ruby.
+The verified interpreter-pinned equivalent is:
+
+```sh
+mise exec ruby@3.3.9 -- ruby -S bundle install
+mise exec ruby@3.3.9 -- ruby -rbundler/setup -S rake
+```
+
+Create disposable loopback-only databases, never application databases:
+
+```sh
+docker run --detach --name statesman-driver-pg-20260912 \
+  --publish 127.0.0.1:55439:5432 \
+  --env POSTGRES_HOST_AUTH_METHOD=trust --env POSTGRES_DB=statesman_driver \
+  postgres:18-alpine
+docker run --detach --name statesman-driver-mysql-20260912 \
+  --publish 127.0.0.1:53309:3306 \
+  --env MYSQL_ALLOW_EMPTY_PASSWORD=yes --env MYSQL_DATABASE=statesman_driver \
+  mysql:8.4
+```
+
+Wait for initialization, then run:
+
+```sh
+SOLID_OBJECTS_DATABASE_URL=postgresql://postgres@127.0.0.1:55439/statesman_driver \
+  mise exec ruby@3.3.9 -- ruby -rbundler/setup -S rake test
+SOLID_OBJECTS_DATABASE_URL=mysql2://root@127.0.0.1:53309/statesman_driver \
+  mise exec ruby@3.3.9 -- ruby -rbundler/setup -S rake test
+```
+
+External test databases must be empty before each run. The harness creates
+the schema and resets its rows. It uses a pool of 20 because six racing callers
+hold connections at a barrier. SQLite creates and removes its own temporary
+database. Docker database fixtures can be removed and recreated after use.
+
+At the end of this validation run, the repository was a local, unpublished
+candidate. No core changes, JavaScript changes, remote repository creation,
+commits, pushes, or releases were performed during that validation.

data/lib/statesman/solid_objects/actor.rb

@@ -0,0 +1,55 @@
+# rbs_inline: enabled
+
+module Statesman
+  module SolidObjects
+    class Actor < ::SolidObjects::Actor
+      actor_type "statesman-transition"
+
+      attribute :sort_keys, default: -> { {} }
+
+      # @rbs (registration: String, parent_id: String, to: String, metadata: Hash[String, untyped]) -> Integer
+      def transition(registration:, parent_id:, to:, metadata:)
+        definition = SolidObjects.registrations.fetch(registration)
+        parent = parent_for(definition, parent_id)
+        from = definition.history(parent).last&.to_state || definition.machine_class.initial_state
+        stage_transition(definition, parent, to, metadata, from:, operation: "transition")
+      end
+
+      # @rbs (registration: String, parent_id: String) -> Integer
+      def initialize_state(registration:, parent_id:)
+        definition = SolidObjects.registrations.fetch(registration)
+        parent = parent_for(definition, parent_id)
+        existing = definition.history(parent).first
+        return existing.sort_key if existing
+
+        stage_transition(definition, parent, definition.machine_class.initial_state, {}, from: "", operation: "initialize_state")
+      end
+
+      private
+
+      # @rbs (Registration, String) -> untyped
+      def parent_for(definition, parent_id)
+        parent = definition.parent_class.find(parent_id)
+        raise ArgumentError, "parent does not match actor identity" unless definition.actor_id(parent) == actor_id
+
+        parent
+      end
+
+      # @rbs (Registration, untyped, String, Hash[String, untyped], from: String, operation: String) -> Integer
+      def stage_transition(definition, parent, to, metadata, from:, operation:)
+        registration = definition.name
+        parent_id = parent.id.to_s
+
+        counter = definition.association.to_s
+        current_key = sort_keys.fetch(counter) { definition.history(parent).maximum(:sort_key) || 0 }
+        sort_key = current_key + 10
+        self.sort_keys = sort_keys.merge(counter => sort_key)
+        commit_action(:statesman_transition, registration:, parent_id:, to:, metadata:, sort_key:, operation:)
+        if definition.after_commit == :effect
+          emit(:statesman_after_commit, registration:, parent_id:, sort_key:, from:)
+        end
+        sort_key
+      end
+    end
+  end
+end

data/lib/statesman/solid_objects/adapter.rb

@@ -0,0 +1,95 @@
+# rbs_inline: enabled
+
+module Statesman
+  module SolidObjects
+    class Adapter
+      # @rbs @transition_class: untyped
+      # @rbs @parent_model: untyped
+      # @rbs @observer: untyped
+      # @rbs @definition: Registration
+      # @rbs @authorization_context: untyped
+
+      attr_reader :transition_class, :parent_model
+
+      # @rbs (untyped, untyped, untyped, ?Hash[Symbol, untyped]) -> void
+      def initialize(transition_class, parent_model, observer, options = {})
+        @transition_class = transition_class
+        @parent_model = parent_model
+        @observer = observer
+        @definition = SolidObjects.registrations.fetch(options.fetch(:solid_objects_registration).to_s)
+        raise ArgumentError, "transition class does not match registration" unless transition_class == @definition.transition_class
+
+        @definition.actor_id(parent_model)
+        @authorization_context = options[:authorization_context]
+      end
+
+      # @rbs (String | Symbol | nil, String | Symbol, ?Hash[untyped, untyped]) -> untyped
+      def create(from, to, metadata = {})
+        return execution.persist(@observer, from.to_s, to.to_s, metadata) if execution
+
+        reference = Actor.ref(definition.actor_id(parent_model)).sync(authorization_context: @authorization_context)
+        identity = { registration: definition.name, parent_id: parent_model.id.to_s }
+        sort_key = if from.nil?
+          reference.initialize_state(**identity)
+        else
+          reference.transition(**identity, to: to.to_s, metadata:)
+        end
+        definition.history(parent_model).find_by!(sort_key:)
+      rescue ::SolidObjects::Rejected => rejection
+        raise unless [ "transition_failed", "guard_failed" ].include?(rejection.code)
+
+        from = rejection.details.fetch("from")
+        to = rejection.details.fetch("to")
+        raise Statesman::GuardFailedError.new(from, to, nil, parent_model) if rejection.code == "guard_failed"
+
+        raise Statesman::TransitionFailedError.new(from, to)
+      end
+
+      # @rbs (?force_reload: bool) -> untyped
+      def last(force_reload: false)
+        authorize_read("last")
+        transition_class.uncached { definition.history(parent_model).last }
+      end
+
+      # @rbs (?force_reload: bool) -> Array[untyped]
+      def history(force_reload: false)
+        authorize_read("history")
+        transition_class.uncached { definition.history(parent_model).to_a }
+      end
+
+      # @rbs () -> nil
+      def reset
+        nil
+      end
+
+      private
+
+      attr_reader :definition
+
+      # @rbs () -> Integer
+      def next_sort_key
+        (last&.sort_key || 0) + 10
+      end
+
+      # @rbs () -> Execution?
+      def execution
+        current = Execution.current
+        current if current&.matches?(definition, parent_model)
+      end
+
+      # @rbs (String) -> void
+      def authorize_read(operation)
+        return if execution
+
+        allowed = ::SolidObjects.configuration.authorize_query.call(
+          actor_type: Actor.actor_type,
+          actor_id: definition.actor_id(parent_model),
+          operation:,
+          arguments: {},
+          authorization_context: @authorization_context
+        )
+        raise ::SolidObjects::Unauthorized, "transition read is not authorized" unless allowed
+      end
+    end
+  end
+end