.. SPDX-License-Identifier: CC-BY-4.0 SPDX-FileCopyrightText: Netresearch DTT GmbH .. include:: /Includes.rst.txt .. _api-events: ====== Events ====== PSR-14 events this extension dispatches, and what you may rely on about them. Each is ``@api``: within a major version it is not removed, its properties do not disappear and their types do not change. Listeners are registered the ordinary TYPO3 way, in your own extension's :file:`Configuration/Services.yaml`. .. _api-events-after-ai-record-written: AfterAiRecordWrittenEvent ========================= :php:`Netresearch\NrLlm\Event\AfterAiRecordWrittenEvent` Dispatched once per successful editorial write, after the write has landed and been read back by the tool that made it. For a run with an assignment scope it is dispatched before the call's transaction is committed, under that scope (see below). It answers three questions and no fourth. .. confval:: correlationId :type: string The agent run's uuid, which is the correlation id of everything that run did. It is what :sql:`tx_nrllm_agentrun.uuid` holds, so a listener that needs the run — its actor, its configuration, its trace — resolves it by this value. Never empty. .. confval:: record :type: :php:`Netresearch\NrLlm\Domain\ValueObject\RecordReference` The row the write produced or changed: a table name and a uid, and :php:`__toString()` renders them as ``pages:42``. .. confval:: kind :type: :php:`Netresearch\NrLlm\Domain\Enum\WriteKind` ``WriteKind::CREATED`` when a record is created, ``WriteKind::UPDATED`` when it is changed, ``WriteKind::TEXT_UNCHANGED`` when the call wrote no AI text: it was moved, published or copied, only settings changed, or a draft still holds the source text, and ``WriteKind::DELETED`` when the delete tool soft-deletes it. A deletion still names the target row; the event carries no copy of its former values. A listener ---------- .. code-block:: php use Netresearch\NrLlm\Domain\Enum\WriteKind; use Netresearch\NrLlm\Event\AfterAiRecordWrittenEvent; final readonly class LabelAiWrittenPages { public function __construct( // Your own service: nr_llm records the fact (ADR-239), and what // a site says about an AI-written record is the site's decision. private AiTransparencyLabelRepository $labels, ) {} public function __invoke(AfterAiRecordWrittenEvent $event): void { if ($event->record->table !== 'pages') { return; } if (!in_array($event->kind, [WriteKind::CREATED, WriteKind::UPDATED], true)) { return; } $this->labels->record( $event->record->uid, $event->kind === WriteKind::CREATED ? 'ai-generated' : 'ai-assisted', $event->correlationId, ); } } .. code-block:: yaml services: Vendor\Extension\EventListener\LabelAiWrittenPages: tags: - name: event.listener identifier: 'vendor/label-ai-written-pages' What it deliberately does not carry ----------------------------------- **No record payload.** Not the field values, not a before/after, not a rendered excerpt, not the tool's name. A payload is a copy, and a copy of editorial content is a second place for it to leak from and a second place for it to go stale. :confval:`record` names the row; read it yourself, under your own permissions, at the moment you need it. **One listener of ours, which only records the fact.** :php:`MarkAiWrittenRecord` sets ``tx_nrllm_ai_written`` on ``pages`` and ``tt_content`` (:ref:`ADR-239 `). An Article 50 transparency label, a badge in the page module, a line in an existing editorial audit trail and a nightly compliance report are four different artefacts with four different owners; which of them your site wants is your decision (:ref:`ADR-187 `). **No actor.** Which backend user the run acted for is persisted on the run; resolve it by :confval:`correlationId` rather than expecting a second copy of an identity on every event. Two properties worth knowing before you write a listener -------------------------------------------------------- **It fires before the run trace persists its step for the same call.** Do not try to join the run's trace for this write — it is not there yet. Everything the event promises is on the event. **A listener that throws is logged, not propagated.** The write has already landed and a human has already approved it, so a broken listener does not fail the run — it produces an ``error``-level log entry naming the record. Do not rely on an exception to signal anything back to the extension. In a run with an assignment scope, a DataHandler write of the listener outside the scope does fail the call (see below). **It can fire twice for one record.** The agent queue is at-least-once: a run whose lease is lost may be re-executed, and an idempotent write that runs twice dispatches twice with the same :confval:`correlationId` and :confval:`record`. Deduplicate on that pair if your listener must act once per record. A non-idempotent write is never auto-retried, so it cannot double this way. .. _api-events-assignment-scope: A listener of a run with an assignment scope -------------------------------------------- A run can be bound to the scope of its assignment (:ref:`ADR-295 `). Its write events, this one and the internal ``AiLabelWriteEvent``, are then dispatched while the scope holds the call and before its transaction is committed: the write the event names can still be rolled back after your listener ran, by another listener's write outside the scope or by a failed commit. Keep effects outside the database (a mail, a webhook, a queue message) out of such a listener, or make them tolerate a write that did not stay. A DataHandler write of a listener is held to the scope like the call's own write: a write outside the scope rolls back the whole call, the call's own write included, and the model is told which record and which rule. A write of the record the call wrote, or of its draft, is inside the scope. When TYPO3 adds an entry for a translation in a language the scope does not admit to such a write, the entry is left out without a refusal, as for the call's own write, and the translation gets no version, when the write synchronises nothing: the added entry holds only synchronised fields and ``l10n_state``, no submitted entry names a synchronised field, and no inline or file field in it lists a child record. Any other such entry is judged as before; the scope refuses it and the call fails. On MySQL and MariaDB a ``TCEMAIN.clearCacheCmd`` group flush in a listener's run commits the call early, and a later violation can no longer roll it back (:ref:`ADR-295 `). A listener that has to write outside the scope, a log record on a storage page for example, wraps exactly that write and gives the reason: .. code-block:: php use Netresearch\NrLlm\Service\Tool\Scope\WriteOutsideTheAssignmentScope; WriteOutsideTheAssignmentScope::run( 'editorial audit log of AI writes', fn () => $this->auditLog->record($event), ); The write is not judged, is listed with the call's changes, and is logged as a warning with the reason; a rollback of the call takes it back with the rest. This works only while such an event is dispatched: called anywhere else, during a tool's own execution too, the write is held to the scope as before. Nothing in nr_llm calls it, so without an integrator's code no listener write leaves the scope.