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 Configuration/Services.yaml.

AfterAiRecordWrittenEvent 

NetresearchNrLlmEventAfterAiRecordWrittenEvent

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.

correlationId
type

string

The agent run's uuid, which is the correlation id of everything that run did. It is what 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.

record
type

NetresearchNrLlmDomainValueObjectRecordReference

The row the write produced or changed: a table name and a uid, and __toString() renders them as pages:42.

kind
type

NetresearchNrLlmDomainEnumWriteKind

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 

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,
        );
    }
}
Copied!
services:
  Vendor\Extension\EventListener\LabelAiWrittenPages:
    tags:
      - name: event.listener
        identifier: 'vendor/label-ai-written-pages'
Copied!

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. 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. MarkAiWrittenRecord sets tx_nrllm_ai_written on pages and tt_content (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 (ADR-187).

No actor. Which backend user the run acted for is persisted on the run; resolve it by 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 correlationId and 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.

A listener of a run with an assignment scope 

A run can be bound to the scope of its assignment (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 (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:

use Netresearch\NrLlm\Service\Tool\Scope\WriteOutsideTheAssignmentScope;

WriteOutsideTheAssignmentScope::run(
    'editorial audit log of AI writes',
    fn () => $this->auditLog->record($event),
);
Copied!

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.