<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-06-03-3-effector-actor-model/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-03-3-effector-actor-model/</id>
  <title>ADR 2026-06-03-3: Effector/Actor Model</title>
  <updated>2026-06-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-06-03-3-effector-actor-model/"/>
  <summary>Defines an Effector as an Actor realized inside the Execution domain, but keeps it documentation vocabulary — no code type until a real bug demands one.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The spec-kitty codebase uses actor-identity vocabulary in three distinct places:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Status/event log&lt;/strong&gt;: the &lt;code dir=&quot;auto&quot;&gt;actor&lt;/code&gt; field on &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; records who
performed a lane transition (e.g., &lt;code dir=&quot;auto&quot;&gt;&quot;claude&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;&quot;human&quot;&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retrospective log&lt;/strong&gt;: the actor field on retrospective entries records who
authored an observation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission run engine&lt;/strong&gt;: the runtime-session concept of who is executing a
mission run.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These three vocabularies are currently fragmented — they use similar words but
have no shared type and no formal relationship. The doc-01–doc-17 analysis in
issue #1666 introduced the concept of an &lt;strong&gt;Effector&lt;/strong&gt;: the Actor as realized inside
the Execution domain.&lt;/p&gt;
&lt;p&gt;The question is whether to materialize &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; as a code type now, or to
hold it as vocabulary only until a concrete need forces a code materialization.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;effector-is-a-named-concept-in-docs-only&quot;&gt;Effector Is a Named Concept in Docs Only&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Definition&lt;/strong&gt;: An Effector is an Actor realized inside the Execution domain.
It is the execution-bound realization of an Actor: the entity that performs
actions within a mission run, producing or consuming communication artefacts
(commits, PRs, comments).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision: no code type until a concrete bug triggers materialization.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The concept is modeling vocabulary. The three existing actor-identity vocabularies
(status events, retrospective log, mission run engine) are not currently required
to share a type; they happen to use the same field name but serve different
query patterns. Materializing a &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; type prematurely would:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Require join logic across three schema layers that have no current consumer.&lt;/li&gt;
&lt;li&gt;Create a shared type with no enforcement boundary to prevent actor-kind
confusion from re-emerging.&lt;/li&gt;
&lt;li&gt;Add schema migration overhead for all three layers without delivering user value.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;materialization-trigger&quot;&gt;Materialization Trigger&lt;/h3&gt;
&lt;p&gt;Materialize &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; as a code type when &lt;strong&gt;either&lt;/strong&gt; of the following is true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A concrete actor-kind-mismatch bug is filed — i.e., code confuses a status
event actor with a run-engine actor, or with a retrospective actor, and the
confusion causes incorrect behavior.&lt;/li&gt;
&lt;li&gt;A feature requires joining status/decision/retrospective logs on actor
identity — i.e., a query needs to answer “show me all actions by actor X
across all three log types in a single result set.”&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Neither trigger is currently active.&lt;/p&gt;
&lt;h3 id=&quot;when-materialized-placement&quot;&gt;When Materialized: Placement&lt;/h3&gt;
&lt;p&gt;When &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; is materialized, it must be placed in a low-layer shared
location so all three existing vocabularies can converge:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preferred: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/kernel/actor.py&lt;/code&gt; (shared kernel layer)&lt;/li&gt;
&lt;li&gt;Alternative: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/actor.py&lt;/code&gt; (top-level if kernel does not exist)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;It must not be placed inside &lt;code dir=&quot;auto&quot;&gt;status/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;runtime/&lt;/code&gt;, or any single-domain
module, because the type must be importable by all three domains without
creating an illegal up-import.&lt;/p&gt;
&lt;h3 id=&quot;relationship-to-actor&quot;&gt;Relationship to Actor&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;Actor&lt;/code&gt; is the broader identity concept (who is making a request, as understood
by the governance or mission management layer). &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; is the execution-
domain specialization of &lt;code dir=&quot;auto&quot;&gt;Actor&lt;/code&gt;. The relationship is:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Actor (broader, may exist outside execution context)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└─ Effector (Actor ∩ Execution domain)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This is a conceptual relationship, not a Python inheritance hierarchy, until
materialization.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;what-stays-the-same&quot;&gt;What stays the same&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;All three existing actor-identity vocabularies (status events, retrospective
log, run engine) are unchanged. They continue to use &lt;code dir=&quot;auto&quot;&gt;str&lt;/code&gt; or existing enum
values for actor identity.&lt;/li&gt;
&lt;li&gt;No schema migration is required.&lt;/li&gt;
&lt;li&gt;No new code is written as part of this ADR.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-is-now-explicit&quot;&gt;What is now explicit&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; is a named term with a definition in the project glossary and
this ADR. Writers of architecture docs, glossary entries, and design docs
may use the term precisely.&lt;/li&gt;
&lt;li&gt;The decision not to materialize is explicit, with a documented trigger for
when materialization becomes correct.&lt;/li&gt;
&lt;li&gt;The placement decision (kernel layer) is pre-decided so that when
materialization is triggered, there is no debate about where the type goes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-changes-downstream&quot;&gt;What changes downstream&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;No code changes from this ADR.&lt;/li&gt;
&lt;li&gt;WP01 adds &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; to the project glossary with this ADR as its reference.&lt;/li&gt;
&lt;li&gt;Future feature work that would trigger materialization must reference this
ADR and document that the trigger condition was met.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/execution-state-domain-remediation-01KT6HVH/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Issue #1619: Strangler Fig sequence&lt;/li&gt;
&lt;li&gt;Issue #1674: ADR gate requirement&lt;/li&gt;
&lt;li&gt;Issue #1666: doc-01–doc-17 design analysis (Effector concept origin)&lt;/li&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-06-03-1-execution-state-domain-model/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-06-03-1-execution-state-domain-model.md&lt;/code&gt;&lt;/a&gt;: domain model gate (Shared Kernel placement)&lt;/li&gt;
&lt;li&gt;Glossary: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/glossary/&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;communication artefact&lt;/code&gt; entries&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
