xtr-workflow 5.1.0__py3-none-any.whl

xtr_workflow/.agents/skills/xtr-workflow/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: xtr-workflow
+description: How to move an object through a workflow or a state machine with xtr-workflow — definitions built in code, in configuration or declared on a class, guards that block a transition, events at every step, and definitions dumped as Graphviz, PlantUML or Mermaid. Use when an object has a status, a state, a stage or a lifecycle (draft/review/published, new/paid/shipped, open/assigned/closed), when a move must be checked before it happens or refused with a reason, when something must react to a status change, when an object must be in several places at once or a step must wait for two others, when adding WorkflowBundle to an application on xtr-dependency-injection, or when drawing a state diagram with workflow:dump.
+---
+
+# xtr-workflow
+
+A **definition** is the places an object can be in and the named transitions that move it between
+them. A **state machine** keeps the object in exactly one place; a **workflow** is a Petri net — it
+can be in several, and a transition consumes and produces weighted tokens. Events go out at every
+step through xtr-event-dispatcher; see the `xtr-event-dispatcher` skill for listeners in general.
+
+## Quick reference
+
+- Build a definition: `DefinitionBuilder().add_places([...]).add_transitions([...]).build()`, or
+  `Definition(places, transitions, initial_places, metadata_store)`.
+- Run it: `StateMachine(definition, marking_store, dispatcher, name)` or `Workflow(...)`, both from
+  `xtr_workflow`.
+- Ask, then move: `await workflow.can(subject, "publish")`,
+  `await workflow.build_transition_blocker_list(subject, "publish")`,
+  `await workflow.apply(subject, "publish", context)`,
+  `await workflow.get_enabled_transitions(subject)`.
+- Where the marking lives: `MethodMarkingStore(single_state, property)` from
+  `xtr_workflow.marking_store` — the subject's `get_<property>()` / `set_<property>()`, else its
+  attribute. Both its methods are `async`.
+- Declare on a class: `@as_workflow(...)` with `Transition` / `Place` markers and
+  `as_*_listener` methods, from `xtr_workflow.decorator`. See
+  [references/declaring-workflows.md](references/declaring-workflows.md).
+- Events, names and listener decorators: [references/events.md](references/events.md).
+- Guard a transition: a callable taking a `GuardContext` (`xtr_workflow.event_listener`), set as
+  `guard=` on a `TransitionConfig` or a `Transition` marker. Needs `SecurityBundle` listed in
+  `config/bundles.py`: it never comes along with the workflow bundle.
+- Draw it: `GraphvizDumper`, `StateMachineGraphvizDumper`, `PlantUmlDumper`, `MermaidDumper` from
+  `xtr_workflow.dumper`, or the `workflow:dump` command.
+- In an application, with xtr-dependency-injection installed beside the package (it is not a
+  dependency): activate `WorkflowBundle` and configure `WorkflowConfig`. Without the container,
+  everything above works; only `xtr_workflow.bundle` imports it.
+- Everything that may ask a listener is a coroutine; `get_name`, `get_definition`,
+  `get_marking_store`, `get_metadata_store`, definitions, markings, dumpers, validators and the
+  registry are not.
+
+## Move an object through a state machine
+
+The usual case: one place at a time, kept on the subject.
+
+```python
+from xtr_workflow import DefinitionBuilder, StateMachine, Transition
+from xtr_workflow.marking_store import MethodMarkingStore
+
+
+class Article:
+    status: str | None = None
+
+
+definition = (
+    DefinitionBuilder()
+    .add_places(["draft", "review", "published"])
+    .add_transitions(
+        [
+            Transition("request_review", "draft", "review"),
+            Transition("publish", "review", "published"),
+            Transition("reject", "review", "draft"),
+        ]
+    )
+    .build()
+)
+workflow = StateMachine(definition, MethodMarkingStore(True, "status"), name="blog_publishing")
+
+article = Article()
+assert await workflow.can(article, "request_review")
+await workflow.apply(article, "request_review")
+assert article.status == "review"
+```
+
+The first place added is where a subject starts; `set_initial_places(...)` changes that. A subject
+read for the first time is put in the initial places and an `entered` event announces it, with the
+context `{"initial": True}`.
+
+## Wait for two things at once
+
+`Workflow` is the Petri net. `Arc(place, weight)` says how many tokens a transition takes from a
+place or puts in it; a bare place name weighs 1.
+
+```python
+from xtr_workflow import Arc, Definition, Transition, Workflow
+
+definition = Definition(
+    ["new", "paid", "picked", "shipped"],
+    [
+        Transition("split", "new", [Arc("paid"), Arc("picked", 2)]),
+        Transition("ship", [Arc("paid"), Arc("picked")], "shipped"),  # needs both
+    ],
+    "new",
+)
+workflow = Workflow(definition, name="order_fulfilment")
+
+marking = await workflow.apply(order, "split")
+assert marking.get_places() == {"paid": 1, "picked": 2}
+```
+
+Applying a name applies **every** transition of that name the marking enables, so a subject spread
+over places moves out of all of them at once. A transition is known by its identity: two built
+alike are two transitions, each with its own metadata.
+
+## Refuse a move, and say why
+
+```python
+from xtr_workflow.exception import NotEnabledTransitionError, UndefinedTransitionError
+
+blockers = await workflow.build_transition_blocker_list(order, "ship")
+if not blockers.is_empty():
+    reasons = [blocker.get_message() for blocker in blockers]
+
+try:
+    await workflow.apply(order, "ship")
+except NotEnabledTransitionError as error:
+    reasons = [b.get_message() for b in error.get_transition_blocker_list()]
+except UndefinedTransitionError:
+    ...  # no transition of that name at all
+```
+
+Codes on `TransitionBlocker`: `BLOCKED_BY_MARKING` (the places do not hold the tokens),
+`BLOCKED_BY_EXPRESSION_GUARD_LISTENER` (a guard refused), `UNKNOWN` (a listener called
+`set_blocked(True)` without a code of its own). A guard's refusal reads
+`The expression blocks the transition.`, and its `get_parameters()["expression"]` names the guard —
+module and qualified name, `"app.blog.only_an_editor"`. The names keep *expression* for parity with
+that code, a fixed UUID: there is no expression language here.
+
+## Guard a transition
+
+A guard is a callable handed a `GuardContext`, answering whether the transition may run — at once
+or through an awaitable. Every guard of the transition runs, and each refusal adds a blocker.
+
+```python
+from xtr_workflow.event_listener import GuardContext
+
+
+async def only_an_editor(context: GuardContext) -> bool:
+    return await context.authorization_checker.is_granted("ROLE_EDITOR", context.subject)
+
+
+def not_locked(context: GuardContext) -> bool:
+    return not context.subject.locked
+```
+
+The context carries `subject`, `token` (`None` when no one is authenticated), `user`, `role_names`
+(the token's roles plus everything they reach), `authorization_checker` and `trust_resolver`.
+Importing it needs no security package. Running one does: set it with
+`TransitionConfig(..., guard=only_an_editor)` or `Transition(..., guard=only_an_editor)`, and list
+`SecurityBundle` (`from xtr_security.bundle import SecurityBundle`) in `BUNDLES` beside
+`WorkflowBundle`, or the build fails saying so. Listing the workflow bundle never activates it: it
+brings the http-kernel bundle and its peers with it.
+
+A guard reads the token of the unit of work its guard event is dispatched in. From a script or a
+console command nobody is authenticated, unless the code opens that unit and says who acts:
+
+```python
+from xtr_dependency_injection import unit_of_work
+from xtr_security_core import TokenStorageInterface, UsernamePasswordToken
+from xtr_workflow import WorkflowInterface
+
+async with unit_of_work(container) as unit:  # container: the booted kernel's
+    storage = await unit.get(TokenStorageInterface)
+    storage.set_token(UsernamePasswordToken(editor, "console", roles=editor.get_roles()))
+    blog = await unit.get(WorkflowInterface, "blog_publishing")
+    await blog.apply(article, "publish")  # the guards see the editor
+```
+
+## Draw the definition
+
+```python
+from xtr_workflow.dumper import MermaidDumper, StateMachineGraphvizDumper
+
+print(MermaidDumper(MermaidDumper.TRANSITION_TYPE_STATEMACHINE).dump(definition, marking))
+print(StateMachineGraphvizDumper().dump(definition, options={"label": "Blog"}))
+```
+
+`GraphvizDumper` draws a workflow, `StateMachineGraphvizDumper` a state machine; `PlantUmlDumper`
+and `MermaidDumper` take the transition style (`STATEMACHINE_TRANSITION` /
+`TRANSITION_TYPE_STATEMACHINE` for labelled arrows, `WORKFLOW_TRANSITION` /
+`TRANSITION_TYPE_WORKFLOW` for transition nodes). Metadata styles it: `label`, `bg_color`,
+`description`, `color`, `arrow_color`.
+
+With the console bundle active:
+
+```sh
+<script> workflow:dump blog_publishing --dump-format=mermaid
+<script> workflow:dump order_fulfilment paid --with-metadata --with-listeners
+<script> workflow:dump order_fulfilment -l "Order fulfilment" | dot -Tpng > wf.png
+```
+
+The places after the name are the marking to highlight; `--dump-format` is `dot` (default), `puml`
+or `mermaid`, and any other value draws `dot`. Only `dot` reads the options: `-l` / `--label` and
+`--with-metadata` for both kinds, `--with-listeners` for a workflow only — a state machine has no
+transition node to list them on. PlantUML titles with the workflow's name; Mermaid reads no option.
+The output is raw diagram source, meant to be piped.
+
+## Testing
+
+Nothing needs a kernel, a clock or a dispatcher: build the definition, build the workflow, assert.
+
+```python
+from xtr_workflow import DefinitionBuilder, StateMachine, Transition
+
+
+async def test_a_draft_cannot_be_published() -> None:
+    definition = (
+        DefinitionBuilder()
+        .add_places(["draft", "review", "published"])
+        .add_transitions([Transition("publish", "review", "published")])
+        .build()
+    )
+    workflow = StateMachine(definition, name="blog")
+
+    assert not await workflow.can(Article(), "publish")
+```
+
+- To test what went out, hand the workflow a dispatcher that records what it is given.
+- To test a guard, call it with a `GuardContext` built by hand: the fields are plain data and two
+  protocols, so a fake checker is a class with `is_granted`.
+- To test a dump, compare the string; the dumpers are deterministic and read no clock.
+- A bundle test calls `await assert_zero_config(WorkflowBundle)`: with no workflow it builds, boots,
+  and its `Registry` raises `Unable to find a workflow for class "object".`
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`WorkflowBundle` and writes `<app>/config/packages/workflow.py` with the bundle's own defaults — no
+workflow — and a commented starter one. That is the steps below a recipe can do; the workflows
+themselves, and listing the security bundle for guards, it prints for you to make.
+
+1. **Install** — `uv add xtr-workflow xtr-dependency-injection`: the bundle needs the container
+   installed beside it, never as an extra. Install xtr-security beside it for guards, xtr-console
+   for `workflow:dump`, xtr-logging for the audit trail's `workflow` channel.
+2. **Activate** — `WorkflowBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`
+   (`from xtr_workflow.bundle import WorkflowBundle`). For guards, `SecurityBundle: {"all": True}`
+   too (`from xtr_security.bundle import SecurityBundle`), with the security bundle's own steps.
+3. **Brings along** — the event dispatcher bundle always; the logging and console bundles when
+   their packages are installed. Never the security bundle — guards need it listed. A workflow
+   needing a bundle that is not active fails the build naming it.
+4. **Configure** — `<app>/config/packages/workflow.py`. A workflow declared with `@as_workflow`
+   needs no entry; `WorkflowConfig()` with no workflow is valid.
+
+   ```python
+   # <app>/config/packages/workflow.py
+   from xtr_dependency_injection import configure
+   from xtr_workflow import WorkflowType
+   from xtr_workflow.bundle import (
+       AuditTrailConfig,
+       MarkingStoreConfig,
+       TransitionConfig,
+       WorkflowConfig,
+       WorkflowDefinitionConfig,
+   )
+
+   from app.blog import Article, only_an_editor
+
+
+   @configure
+   def workflow() -> WorkflowConfig:
+       return WorkflowConfig(
+           workflows={
+               "blog_publishing": WorkflowDefinitionConfig(
+                   type=WorkflowType.STATE_MACHINE,
+                   supports=Article,
+                   marking_store=MarkingStoreConfig(property="status"),
+                   audit_trail=AuditTrailConfig(enabled=True),
+                   places=("draft", "review", "published"),
+                   transitions={
+                       "request_review": TransitionConfig(froms="draft", tos="review"),
+                       "publish": TransitionConfig(
+                           froms="review", tos="published", guard=only_an_editor
+                       ),
+                       "reject": TransitionConfig(froms="review", tos="draft"),
+                   },
+               ),
+           },
+       )
+   ```
+
+   Lists take the shortest shape that says them: one supported class or initial place on its own,
+   places as names, string-enum members or `PlaceConfig`s — or keyed by name — transitions keyed by
+   name, arcs as a name, an enum member, an `Arc` or an `ArcConfig`.
+5. **Inject** — each workflow is registered once, as `WorkflowInterface` under its name:
+   `Annotated[WorkflowInterface, Target("blog_publishing")]`, or
+   `ServiceLocator[WorkflowInterface]` by name, or `Registry` by subject (`registry.get(article)`,
+   for a workflow listing `supports` or a `support_strategy`). Its `Definition` (`xtr_workflow`)
+   and `InMemoryMetadataStore` (`xtr_workflow.metadata`) are under the name too. In debug mode the
+   service is a `TraceableWorkflow` (`xtr_workflow.debug`): its `get_calls()` holds a record per
+   call — `method`, `duration` (ms), `args`, `previous_marking`, and `return` or `exception` — and
+   code needing the concrete class calls `get_inner()`.
+6. **Environment** — nothing. **Ignore** — nothing.
+7. **Check** — `debug:bundles` lists `workflow` as active; `workflow:dump <name>` prints the
+   definition the container built.
+8. **Remove** — drop the `BUNDLES` entry, delete every `@as_workflow` class and workflow listener;
+   `uv run xtr-recipes recipes:remove xtr-workflow` deletes
+   `<app>/config/packages/workflow.py`, unless you edited it, in which case it is moved aside to
+   `workflow.py.removed`. Then `uv remove xtr-workflow`.
+
+## Errors
+
+All derive from `WorkflowError` (`xtr_workflow.exception`):
+
+- `InvalidArgumentError` (also a `ValueError`) — a value it cannot use: a weight below 1, an empty
+  place name, unmarking a place that holds nothing, an unknown entry in `events_to_dispatch`, no
+  workflow for a subject or several, a direction or transition type a dumper does not know.
+- `LogicError` — a state that cannot be: an empty marking with no initial place, a place the
+  definition lacks, a subject with neither accessor nor attribute for its marking, a class
+  decorated `@as_workflow` twice, a workflow name taken twice, a bundle a workflow needs that is
+  not active, a place outside the `places=` enum of an `@as_workflow` class, a `WorkflowTrait`
+  used before `set_workflow(...)`.
+- `InvalidDefinitionError` — a validator refused the definition at build.
+- `TransitionError` — carrying the subject, the transition's name, the workflow and the context:
+  `UndefinedTransitionError` (no transition of that name) and `NotEnabledTransitionError` (blocked,
+  with the blocker list).
+- `WorkflowRuntimeError` — a failure while running.
+
+`Transition` raises a plain `TypeError` for an arc that is neither a place name nor an `Arc`.
+
+## Do not
+
+- Do not call `apply`, `can`, `get_marking` or the blocker list without `await`: every one is a
+  coroutine, and so are both methods of a marking store.
+- Do not import `Transition` from `xtr_workflow` where you mean the marker: the marker is
+  `xtr_workflow.decorator.Transition`, and the two are different classes.
+- Do not write `from=` / `to=`: the keywords are `froms=` and `tos=`.
+- Do not expect a guard to see a token outside a request or a message: the unit of work opened for
+  a guard event in a console command has nobody authenticated, so a role check refuses. Open the
+  unit yourself and set a token in it (see *Guard a transition*), or guard on the subject's own
+  data where a transition must run headless.
+- Do not expect listing `WorkflowBundle` to activate the security bundle, even with xtr-security
+  installed: guards need `SecurityBundle` listed beside it.
+- Do not leave a concrete class carrying `@self` workflow listeners inside a scanned package — the
+  build fails with nothing to resolve the name to. Make a shared listener base abstract, or keep it
+  out of the scan.
+- Do not rely on `TransitionConfig(weight=...)`: it is validated and read by nothing. Weigh the arc
+  instead, with `ArcConfig(place, weight)`.
+- Do not write a guard as a string expression; there is no expression language here, and no
+  `is_valid(...)`.
+- Do not subclass a `@as_workflow` class expecting a second workflow: the declaration is the
+  decorated class's alone.
+- Do not inject `Workflow` or `StateMachine` from the container; the key is `WorkflowInterface`
+  under the workflow's name.

xtr_workflow/.agents/skills/xtr-workflow/references/declaring-workflows.md

@@ -0,0 +1,170 @@
+# Declaring a workflow on a class
+
+`@as_workflow` records on a class what the configuration would otherwise say. The workflow bundle
+reads the declaration from every class its scan finds and registers the workflow; without the
+container the declaration is inert data, and the class is just a class.
+
+Everything here comes from `xtr_workflow.decorator`.
+
+## A full example
+
+```python
+from enum import StrEnum
+from typing import Annotated, ClassVar
+
+from xtr_workflow import WorkflowTrait, WorkflowType
+from xtr_workflow.decorator import Place, Transition, as_guard_listener, as_workflow
+from xtr_workflow.event import GuardEvent
+
+
+class Step(StrEnum):
+    NEW = "new"
+    PROCESSING = "processing"
+    DONE = "done"
+    FAILED = "failed"
+
+
+class Task:
+    step: Step | None = None
+    blocked: bool = False
+
+
+@as_workflow(
+    supports=Task,
+    marking_property="step",
+    places=Step,
+    place_markers={Step.NEW: Place(description="Waiting to be picked up", initial=True)},
+    metadata={"title": "Task"},
+)
+class TaskStateMachine(WorkflowTrait):
+    START: ClassVar[Annotated[str, Transition(froms=Step.NEW, tos=Step.PROCESSING)]] = "start"
+    FINISH: ClassVar[
+        Annotated[
+            str,
+            Transition(froms=Step.PROCESSING, tos=Step.DONE),
+            Transition(froms=Step.FAILED, tos=Step.DONE),
+        ]
+    ] = "finish"
+    FAIL: ClassVar[Annotated[str, Transition(froms=Step.PROCESSING, tos=Step.FAILED)]] = "fail"
+
+    async def start(self, task: Task) -> None:
+        _ = await self.apply(task, self.START, {"started_by": "start()"})
+
+    @as_guard_listener(transition=START)
+    def refuse_blocked_tasks(self, event: GuardEvent) -> None:
+        subject = event.get_subject()
+        if isinstance(subject, Task) and subject.blocked:
+            event.set_blocked(True, "The task is blocked.")
+```
+
+## `@as_workflow` arguments
+
+| Argument | Does |
+| --- | --- |
+| `name=` | The workflow's name; derived from the class otherwise |
+| `type=` | `WorkflowType.STATE_MACHINE` (default) or `WorkflowType.WORKFLOW` |
+| `supports=` | The class, or classes, of the subjects it moves — puts it in the `Registry` |
+| `support_strategy=` | The qualifier of a `WorkflowSupportStrategyInterface` service instead |
+| `initial_marking=` | The place, or places, a subject starts in |
+| `marking_property=` | The subject's attribute (or `get_`/`set_` pair) keeping the marking |
+| `marking_store=` | The qualifier of a `MarkingStoreInterface` service instead |
+| `description=` | Kept under `metadata["description"]` |
+| `metadata=` | The workflow's metadata |
+| `audit_trail=` | `True` logs every move on the `workflow` channel |
+| `events_to_dispatch=` | Which events ever go out; see `references/events.md` |
+| `definition_validators=` | Validators run on the definition besides the type's own |
+| `places=` | A string enum whose every member is a place, and outside which no place is named |
+| `place_markers=` | A `Place` per enum member that needs one, keyed by the member |
+
+- The derived name is the class's name snake-cased, without a `Workflow` or `StateMachine` suffix:
+  `TaskStateMachine` → `task`, `PullRequestStateMachine` → `pull_request`.
+- `supports` with `support_strategy`, `marking_property` with `marking_store`, or a `description`
+  plus one in `metadata`, each raise `LogicError` at decoration.
+- The declaration belongs to the decorated class alone: the reader looks in the class's own
+  `__dict__`, so a subclass declares nothing unless it is decorated too. Decorating one class twice
+  raises.
+- A name already used by the configuration, or by another class, is a build error naming both.
+- With neither `supports` nor `support_strategy` the workflow is not in the `Registry` — it is
+  reached by injection only.
+
+## The `Transition` marker
+
+`Transition` here is **not** `xtr_workflow.Transition`: it is the marker, and it goes inside
+`Annotated` on a class constant valued with the transition's name.
+
+```python
+SUBMIT: ClassVar[Annotated[str, Transition(froms="draft", tos="review")]] = "submit"
+```
+
+| Argument | Does |
+| --- | --- |
+| `froms=` | The places it leaves: a name, a string-enum member, an `Arc`, or a sequence of those |
+| `tos=` | The places it enters, the same way |
+| `guard=` | A callable taking a `GuardContext`; the transition runs only when it answers true |
+| `description=` | Kept under `metadata["description"]` |
+| `metadata=` | The transition's metadata |
+
+`from` and `to` are not the keywords — `from` is a reserved word, and `froms` / `tos` match
+`Transition.get_froms()` / `get_tos()` on the built transition. Repeat the marker inside one
+`Annotated` to declare several transitions of that name: a state machine needs one per pair of
+places, and a workflow applies every enabled transition of the name at once.
+
+Weigh an arc with `Arc(place, weight)` from `xtr_workflow`; a bare name weighs 1, which is all a
+state machine ever uses.
+
+## The `Place` marker
+
+A place a transition leaves or enters is a place already. `Place` adds one nothing uses, fixes the
+order of the places, or says something about one.
+
+```python
+ARCHIVED: ClassVar[Annotated[str, Place(description="Kept, never shown")]] = "archived"
+```
+
+That holds without `places=`. With it, the enum is the whole list: a `Place` constant — or a
+transition — naming a place outside it fails the build, the error saying the place
+`is not a case of` the enum. Value such a constant with one of the enum's members.
+
+| Argument | Does |
+| --- | --- |
+| `description=` | Kept under `metadata["description"]` |
+| `metadata=` | The place's metadata — `label`, `bg_color` and the rest a dumper reads |
+| `initial=` | The place is in the initial marking, unless `initial_marking=` says otherwise |
+
+**Enum members take no marker of their own.** An annotation on an enum member survives at runtime
+but type checkers reject it, so the markers for an enum's members go in `@as_workflow`:
+
+```python
+@as_workflow(places=Step, place_markers={Step.NEW: Place(initial=True)})
+```
+
+A key that is not a member of the `places` enum raises `LogicError` at decoration.
+
+## `WorkflowTrait`
+
+Mixing it in is optional, and makes the class answer for its own workflow: it delegates every
+`WorkflowInterface` method — `get_marking`, `can`, `build_transition_blocker_list`, `apply`,
+`get_enabled_transitions`, `get_enabled_transition`, `get_name`, `get_definition`,
+`get_marking_store`, `get_metadata_store` — to the workflow handed to `set_workflow(...)`, which
+the bundle calls after building it (the traced one, in debug mode). The class keeps whatever
+constructor it likes.
+
+Called before a workflow is set, every delegate raises `LogicError` naming the class. The workflow
+is kept under a name-mangled attribute, so `_workflow` is free for your own use.
+
+## Listeners on the class
+
+The `as_*_listener` decorators name a workflow with their first positional argument. Inside a class
+decorated `@as_workflow`, leave it out and the listener is that workflow's: the decorator records
+the placeholder `workflow.@self.guard.start`, and `@as_workflow` rewrites it to
+`workflow.task.guard.start` when it decorates the class.
+
+- Keep `@as_workflow` **above** every listener decorator: it resolves what is already recorded.
+- An inherited listener method is resolved per class, so two workflow classes sharing a base each
+  listen to their own workflow.
+- A **concrete** class carrying such declarations inside a scanned package fails the build: there
+  is no workflow to resolve the name to. Make a shared listener base abstract, or keep it out of
+  the scanned packages.
+- A plain function cannot use the placeholder: name the workflow, or listen to every one.
+
+See [events.md](events.md) for the decorators and the names they build.

xtr_workflow/.agents/skills/xtr-workflow/references/events.md

@@ -0,0 +1,123 @@
+# Workflow events
+
+Every step of a move goes out as an event, through xtr-event-dispatcher. Without a dispatcher
+nothing is asked and nothing told: every transition the marking enables is enabled.
+
+## The seven events, in order
+
+| Name | Class | When | A listener can |
+| --- | --- | --- | --- |
+| `workflow.guard` | `GuardEvent` | Before a transition is applied or reported enabled, for every transition the marking enables | Block it: `set_blocked(True, "why")`, or `add_transition_blocker(...)` |
+| `workflow.leave` | `LeaveEvent` | Before the tokens leave each place | React |
+| `workflow.transition` | `TransitionEvent` | While applying the transition | Replace the rest of the call's context: `set_context(...)` |
+| `workflow.enter` | `EnterEvent` | Before the tokens enter each place, before the marking is stored | React |
+| `workflow.entered` | `EnteredEvent` | After the marking is stored — and for a subject's first marking, with the context `{"initial": True}` | React |
+| `workflow.completed` | `CompletedEvent` | The transition has been applied | React |
+| `workflow.announce` | `AnnounceEvent` | Once per transition enabled **after** the move | React |
+
+The guard is never turned off. `announce` asks every guard again to find what is now enabled, so it
+is the one worth turning off when guards are expensive.
+
+## Three names each
+
+Each event is dispatched under its bare name, then narrowed to the workflow, then to each place or
+transition concerned:
+
+```
+workflow.enter
+workflow.blog.enter
+workflow.blog.enter.published      # one per place the transition enters
+```
+
+- `leave`, `enter` and `entered` narrow to a **place** — one dispatch per arc.
+- `guard`, `transition`, `completed` and `announce` narrow to a **transition**.
+- `WorkflowEvents` (from `xtr_workflow`) holds the seven bare names, and `WorkflowEvents.ALIASES`
+  maps each event class to its name. With the bundle active, those aliases are given to the event
+  dispatcher, so a listener annotated `def on_guard(self, event: GuardEvent)` hears
+  `workflow.guard` without naming it.
+
+Each event class has a static `get_name(workflow_name=None, node=None)` building the name:
+`GuardEvent.get_name("blog", "publish")` is `"workflow.blog.guard.publish"`. A node without a
+workflow raises `InvalidArgumentError`.
+
+## Reading an event
+
+Every event answers `get_subject()`, `get_marking()`, `get_transition()` (`None` only for an
+initial marking), `get_workflow_name()` and `get_metadata(key, subject)`.
+`GuardEvent.get_transition()` is never `None`. `LeaveEvent`, `TransitionEvent`, `EnterEvent`,
+`EnteredEvent`, `CompletedEvent` and `AnnounceEvent` also carry `get_context()`.
+
+## The listener decorators
+
+From `xtr_workflow.decorator`. Each builds the event name and otherwise declares an event listener
+the way `@as_event_listener` does, taking the same `method`, `priority`, `dispatcher`, `before` and
+`after` keywords.
+
+| Decorator | Second positional argument |
+| --- | --- |
+| `as_guard_listener(workflow, transition)` | `transition=` |
+| `as_leave_listener(workflow, place)` | `place=` |
+| `as_transition_listener(workflow, transition)` | `transition=` |
+| `as_enter_listener(workflow, place)` | `place=` |
+| `as_entered_listener(workflow, place)` | `place=` |
+| `as_completed_listener(workflow, transition)` | `transition=` |
+| `as_announce_listener(workflow, transition)` | `transition=` |
+
+```python
+from xtr_workflow.decorator import as_entered_listener, as_guard_listener
+from xtr_workflow.event import EnteredEvent, GuardEvent
+
+
+@as_entered_listener("blog", place="published")  # workflow.blog.entered.published
+async def ping_the_feed(event: EnteredEvent) -> None: ...
+
+
+@as_guard_listener("blog")  # workflow.blog.guard — every transition of that workflow
+def refuse_unsigned(event: GuardEvent) -> None:
+    if not event.get_subject().author:
+        event.set_blocked(True, "An article needs an author before it goes out.")
+```
+
+Naming neither a workflow nor a node listens to every workflow. Naming a node without a workflow
+means "the workflow of my class" — see
+[declaring-workflows.md](declaring-workflows.md); outside a class declaring one it is a build
+error.
+
+Adding a listener by hand needs no decorator:
+
+```python
+dispatcher.add_listener("workflow.blog.guard.publish", refuse_unsigned)
+dispatcher.add_listener(WorkflowEvents.ENTERED, announce)
+```
+
+## Choosing what goes out
+
+`events_to_dispatch`, on the constructor, in `WorkflowDefinitionConfig` or on `@as_workflow`, says
+which events a workflow ever dispatches:
+
+| Value | Dispatches |
+| --- | --- |
+| `None` | Every event |
+| `[]` | None of them — the guard still goes out |
+| `["workflow.enter", "workflow.entered"]` | Only those |
+| `["!workflow.announce"]` | Every one but those, so an event added later still goes out |
+
+Mixing listed and `!`-prefixed entries, or blocking `workflow.guard`, raises
+`InvalidArgumentError`.
+
+For one call, pass the context key instead — each a constant on `Workflow`:
+`DISABLE_LEAVE_EVENT`, `DISABLE_TRANSITION_EVENT`, `DISABLE_ENTER_EVENT`,
+`DISABLE_ENTERED_EVENT`, `DISABLE_COMPLETED_EVENT`, `DISABLE_ANNOUNCE_EVENT`.
+
+```python
+await workflow.apply(article, "publish", {Workflow.DISABLE_ANNOUNCE_EVENT: True})
+```
+
+## The audit trail
+
+`AuditTrailListener` (`xtr_workflow.event_listener`) logs an info line per place a subject leaves,
+one for the transition, and one per place it enters, each naming the subject's class and the
+workflow. Built by hand it takes a `LoggerInterface`; with the bundle,
+`audit_trail=AuditTrailConfig(enabled=True)` registers it on the workflow's `leave`, `transition`
+and `enter` events, writing to the `workflow` logging channel — which needs the event dispatcher
+and logging bundles active.