Skip to content

Events reference

The Contacts v1 events on this page are Limiara's first repository-owned public event contracts. Every successful Contacts mutation writes one audit record and one event envelope to the transactional outbox in the same PostgreSQL transaction as the domain change. A failed domain, audit, or outbox write rolls the complete transaction back.

The worker publishes committed envelopes to NATS JetStream with at-least-once semantics. The platform provides a tenant-scoped transactional inbox primitive for native consumers; subscription authorization, plugin lifecycle wiring, retention policy, and operator replay remain planned. Broker publication does not yet provide a public external subscription surface. The architecture boundary is recorded in ADR 0004.

Envelope

Every catalogue entry uses schema version 1 and the following envelope:

Field Type Contacts contract
id UUID Tenant-local event identifier. At-least-once consumers must use (tenant_id, id) for deduplication.
event_type string Stable namespaced type from the catalogue below.
schema_version integer 1 for every event on this page.
source_plugin string platform.contacts.
tenant_id UUID Workspace boundary for the mutation and event.
actor_id UUID Authenticated principal that performed the Contacts mutation.
correlation_id UUID Correlates the mutation with its originating request or workflow.
causation_id UUID or null Identifier of the event that caused this mutation, when applicable.
occurred_at timestamp UTC time at which the event evidence was created.
payload object One of the bounded payloads documented below.

The audit record carries the same tenant, actor, correlation, causation, entity identifier, resulting version, and event identifier. Audit records are operational evidence, not integration events.

Event and outbox identity is the pair (tenant_id, id), not id alone. The same UUID may exist safely in two workspaces. Database lookups, operator tools, consumer ledgers, and plugin-owned references must therefore carry both values.

Delivery semantics

The worker claims bounded due batches from PostgreSQL using expiring ownership leases. Concurrent workers skip rows already locked by another claimant. Each claimed row is validated and encoded as the canonical v1 envelope before it is published to the configured JetStream stream on this subject:

platform.events.v1.tenant.<tenant_id>.<event_type>

The stable JetStream message identity is <tenant_id>:<id>. The worker waits for the broker acknowledgement before setting published_at. A broker error or timeout leaves the row unpublished, clears its live claim, records a bounded failure code, and schedules a bounded exponential retry. The platform stream has a finite file-storage byte ceiling and rejects new messages when full, preserving them in the retryable database outbox instead of silently discarding older broker events.

A deterministically invalid stored envelope is not sent or retried indefinitely. The worker leaves it unpublished, clears the claim, records a bounded error code, sets quarantined_at, and excludes it from later claims. There is no public repair or replay operation. Quarantined records are retained for operator-only diagnosis; an authenticated, audited repair and replay workflow remains future work.

Delivery is not exactly once. A process can receive the broker acknowledgement and stop before it records published_at; the same event may then be published again after its lease expires. JetStream duplicate suppression reduces duplicates within its configured window, but every consumer must make repeated (tenant_id, id) pairs harmless. Ordering across tenants or concurrent mutations is not guaranteed.

The worker reports aggregate backlog, claim, quarantine, attempt, failure, publication, oldest-pending-age, and publish-latency metrics. These metrics have no tenant, event-type, subject, or payload labels. Worker readiness and metrics are internal operational surfaces, not public application or plugin APIs.

Consumer transaction contract

Before selecting a tenant transaction, a consumer host rejects an envelope larger than the platform limit, deserializes the canonical envelope, recomputes its JetStream subject, and requires that subject to match the broker subject exactly. This binds the envelope tenant, event type, source plugin, and schema version to the received subject before database work begins.

Each logical native consumer uses an immutable, namespaced consumer ID. The host begins a transaction with the validated envelope tenant and attempts this marker first:

(tenant_id, consumer_id, event_id)

The marker table has forced RLS and is append-only to the application role. INSERT ... ON CONFLICT DO NOTHING is the concurrency boundary: one delivery owns the marker, while a committed conflict is a duplicate and skips the handler. The marker and handler effects commit together. A handler error or database failure rolls both back, so a later delivery can try again.

The pure processing result maps to broker settlement as follows:

Result Broker action Database state
Applied ACK after commit Marker and effects committed once
Duplicate ACK after confirming the committed marker Existing marker/effects retained; handler not called
Database or transient handler failure NAK with bounded retry policy Marker and attempted effects rolled back
Temporarily unsupported schema NAK during a bounded rollout window, then terminate No marker or effects
Malformed, oversized, unsafe, subject-mismatched, or permanently rejected event TERM No marker or effects

The platform-inbox crate defines this transaction and disposition contract. Mapping an unsupported schema error to a broker action requires the host to state whether its bounded compatibility retry budget remains; there is no implicit unbounded retry default. Issue #32 supplies authorised, enablement-aware subscription registration and that delivery-attempt policy; issue #37 proves the complete API, PostgreSQL, NATS, acknowledgement, redelivery, and lifecycle path. Until then there is no automatically registered public consumer.

A process failure before database commit leaves no durable marker or effect and the unacknowledged message is redelivered. A failure after commit but before ACK also redelivers, but the committed marker returns the duplicate outcome without repeating effects. This is idempotent at-least-once processing, not exactly-once delivery.

Inbox markers currently have indefinite retention. A future cleanup policy must be tied to the longest broker retention and supported replay horizon. External service plugins cannot atomically share this PostgreSQL transaction and must implement their own durable idempotency ledger.

Contacts event catalogue

Event type Trigger Payload
platform.contacts.person-created.v1 A person is created. Person lifecycle payload
platform.contacts.person-updated.v1 A person is updated. Person lifecycle payload
platform.contacts.person-archived.v1 A person is archived. Person lifecycle payload
platform.contacts.person-deleted.v1 A person is moved to the recycle bin. Person lifecycle payload
platform.contacts.person-undeleted.v1 A person is restored from the recycle bin. Person lifecycle payload
platform.contacts.organisation-created.v1 An organisation is created. Organisation lifecycle payload
platform.contacts.organisation-updated.v1 An organisation is updated. Organisation lifecycle payload
platform.contacts.organisation-archived.v1 An organisation is archived. Organisation lifecycle payload
platform.contacts.organisation-deleted.v1 An organisation is moved to the recycle bin. Organisation lifecycle payload
platform.contacts.organisation-undeleted.v1 An organisation is restored from the recycle bin. Organisation lifecycle payload
platform.contacts.custom-field-definition-created.v1 A custom-field definition is created. Custom-field definition lifecycle payload
platform.contacts.custom-field-definition-updated.v1 A custom-field definition is updated. Custom-field definition lifecycle payload
platform.contacts.custom-field-definition-disabled.v1 A custom-field definition is disabled. Custom-field definition lifecycle payload
platform.contacts.custom-field-definition-archived.v1 A custom-field definition is archived. Custom-field definition lifecycle payload

Person lifecycle payload

Field Type Meaning
entity_id string Stable public person identifier, such as per_....
version integer Resulting optimistic-concurrency version.

Organisation lifecycle payload

Field Type Meaning
entity_id string Stable public organisation identifier, such as org_....
version integer Resulting optimistic-concurrency version.

Custom-field definition lifecycle payload

Field Type Meaning
entity_id UUID Identifier of the changed definition.
applies_to string person or organisation.
version integer Resulting optimistic-concurrency version.

Object engine record events

The object engine (ADR 0015) writes its events through the same outbox, with source_plugin set to platform.objects. The full list of engine events is in the objects API; the record lifecycle events share one payload.

Event type Trigger Payload
platform.objects.record-created.v1 A record is created. Record payload
platform.objects.record-updated.v1 A record's values change. Record payload
platform.objects.record-deleted.v1 A record is moved to the recycle bin. Record payload
platform.objects.record-undeleted.v1 A record is restored from the recycle bin. Record payload
platform.objects.record-archived.v1 A record is archived (ADR 0035 G1). Record payload
platform.objects.record-unarchived.v1 An archived record is brought back. Record payload
platform.objects.record-purged.v1 The recycle-bin purge removed a record for good, 15 days after its deletion (ADR 0035 G2). Purged record payload

Record payload

Field Type Meaning
object string The object's API name, such as custom:project.
entity_id string The record's public ID.
version integer Resulting optimistic-concurrency version.
changed_fields array of strings Field API names a create or update set; empty for the lifecycle events.
source string, optional What the change came through: web, api_client, device, automation, quick_action, assistant, import or system. Its detail stays in the audit record.
automation_id UUID, optional The automation that made the change.

Purged record payload

One event per purged record, so a consumer keyed on records (a read model, a search index, an integration) drops it as it handles any other record event; a batch event would make every consumer split it again, and would grow with the batch. The record is gone, so the payload names it and when it went, never its values. The event has no actor; the purge's audit entry, records.recycle_bin.purged, covers the whole batch.

Field Type Meaning
object string The object's API name.
entity_id string The record's public ID; it is never reused.
version integer The record's last version.
deleted_at timestamp When it went to the recycle bin.
purged_at timestamp When the purge removed it.
source string Always system.

Undeleting a record also restores the lookups its deletion cleared on other records (ADR 0035 G3): each restore is a record-updated event of the referencing record, with source system and the field in changed_fields.

Archiving and unarchiving also leave an audit record (records.record.archived, records.record.unarchived) and an updated change-log entry naming archived_at, so devices and change-data-capture clients that know only the earlier kinds read it as an update.

Compatibility and privacy

The .v1 suffix and schema_version: 1 define the compatibility boundary. A documented payload schema may gain optional fields in a compatible release, so consumers must ignore payload fields they do not recognise. The top-level envelope is canonical: the worker removes unknown stored top-level keys, and a new top-level field requires coordinated platform-contract support. Removing a documented field, changing its type or meaning, or making an optional field mandatory requires a new event type and schema version.

Payloads are change notifications rather than row snapshots. They intentionally exclude names, email addresses, telephone numbers, tags, custom-field values, definition API names, labels and descriptions, options, validation rules, data classifications, purpose, retention policy, and encryption settings. An authorised consumer that needs current details must read the owning Contacts API. Never infer exactly-once delivery, global ordering, retention, or replay guarantees from this contract.