Skip to content

ADR-0014: Run identity and lifecycle envelopes

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

  • Status: Accepted 2026-10-09 by the product owner (amends ADR-0010, which stays in force except where this ADR changes it)
  • Date: 2026-10-09
  • Deciders: Dmitry Khaymov (product owner), 2026-10-09; proposed by the 2026-10 independent review
  • Tags: events, envelope, lifecycle, idempotency

Context

ADR-0010 adopts a single canonical event envelope, versioned integration events, deduplication on eventId, and immutability "enabling replay". The code at the inspected revisions has two envelopes and neither matches the documented canonical one:

  • ConnectSoft.Extensions.AI.Factory.Messaging/AgentEventEnvelope carries EventId, OccurredAtUtc, AgentId, TraceId, BlueprintId, AgentOrigin, WorkflowStep and implements MessagingModel.IEvent. It has no tenant, project, run, step, attempt or schema-version field.
  • ConnectSoft.Extensions.AI.Factory.Abstractions/AgentTraceContext carries the same four identifiers.
  • AgentLifecycleStage has Accepted, OutputValidated, Completed, Failed, Escalated. There is no Cancelled stage; cancellation and unexpected exceptions rethrow without any terminal event.
  • Platform's task/event JSON schemas are a third dialect; AgentKit copies them under .ai/registry/sources/.
  • Nothing is event-sourced: no run journal, checkpoint or replay mechanism exists. "Immutable once published, enabling replay" describes a property of messages, not a capability of the system.

Decision

  1. The port-level envelope for Factory integration events is versioned and carries, as required fields: event id, schema version, occurred-at, trusted tenant id, project id, run id, step id and attempt id where applicable, correlation id, causation id, producer identity and event type. Trace id remains diagnostic correlation and is not an authorization or idempotency key.
  2. Lifecycle stages gain Cancelled as a terminal state distinct from Failed; cancellation requests and observed terminations are separate facts. Exception paths must emit a terminal Failed event with a failure class before rethrowing.
  3. Idempotency is defined per trusted scope and operation: same key and same input returns the same logical result; same key with different input is a conflict. Consumers deduplicate on event id within a stated retention window.
  4. State transition and outbox record are written in one transaction of the selected messaging profile (ADR-0012). Publication is not proof of a transition.
  5. Replay is not promised. An append-oriented transition journal is required for recovery; full event sourcing and deterministic replay are separate decisions to be taken on evidence.
  6. Existing envelopes migrate by additive versioning: new fields in a new schema version, old versions readable for a stated window; no second incompatible envelope under an existing version.

Consequences

Positive

  • Every event can be attributed to tenant, project, run and attempt, which the current envelope cannot do.
  • Cancellation becomes observable; today it is invisible.
  • Removes an unmet guarantee (replay) from normative text.

Negative / trade-offs

  • Three dialects (Factory envelope, trace context, Platform JSON schemas) need a compatibility mapping and contract tests.
  • AgentTraceContext and AgentEventEnvelope require additive changes in shared libraries (implementation work outside this task).

Neutral

  • The Platform JSON schemas remain the canonical machine-readable form for task/event contracts once reconciled.

Alternatives considered

Alternative Why not chosen
Keep ADR-0010 wording Documents an envelope and a replay guarantee that do not exist.
Adopt the Platform JSON schema as the only envelope It lacks run/attempt identity too and has no .NET binding; reconciliation is still needed.
Make trace id the run identity Conflates diagnostics with authority; a trace can span several runs and a run several traces.

Evidence

  • ConnectSoft.Extensions.AI.Factory.Messaging/src/.../AgentEventEnvelope.cs L10–35
  • ConnectSoft.Extensions.AI.Factory.Abstractions/src/.../AgentTraceContext.cs L17–43; AgentLifecycleStage.cs L6–22
  • ConnectSoft.Extensions.AI.Factory/src/.../FactoryAgentBase.cs L92–140
  • Verification record V-A1, V-A2, V-A3