Genocs.Saga Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Saga Agent Reference

Purpose

This document is optimized for AI-assisted development sessions. It prioritizes fast retrieval of:

  • What Genocs.Saga is responsible for
  • Which APIs to call for specific goals
  • Where source of truth lives
  • What constraints and runtime behaviors matter

Quick Facts

KeyValue
PackageGenocs.Saga
Project filesrc/Genocs.Saga/Genocs.Saga.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleSaga orchestration abstractions and execution pipeline for distributed workflows
Core themesAddSaga registration, pluggable persistence, saga discovery, coordinated execution, compensation handling, OpenTelemetry trace correlation (Jaeger)

Use This Package When

  • Implementing long-running workflow orchestration with correlation IDs.
  • Managing saga state transitions from pending to completed/rejected.
  • Running compensation logic for rejected saga flows.
  • Using default in-memory saga state/log persistence.
  • Integrating custom saga persistence through ISagaBuilder.
  • Propagating trace context across services for distributed tracing (Jaeger) via SagaTraceContext.

Do Not Assume

  • AddSaga defaults to in-memory persistence when no build action is provided.
  • Saga instances are discovered from currently loaded AppDomain assemblies only.
  • Rejected saga instances are not reinitialized by SagaInitializer.

High-Value Entry Points

Startup and registration

Runtime orchestration pipeline

Saga contracts and lifecycle types

Default in-memory persistence

Context and concurrency helpers

Telemetry correlation

Decision Matrix For Agents

GoalPreferred APINotes
Register saga orchestration with defaultsIServiceCollection.AddSaga()Uses in-memory log and state repository automatically
Register saga orchestration with custom persistenceAddSaga(build => …)Configure ISagaBuilder persistence before registration completes
Process incoming message through all matching saga actionsISagaCoordinator.ProcessAsync(…)Runs discovery, initialization, handling, and post-processing
Resolve and initialize saga instance from messageSagaInitializer.TryInitializeAsyncRejects non-start actions when no state exists
Execute message handler and persist state/logSagaProcessor.ProcessAsyncPersists state and log in finally block
Trigger completion/rejection hooks and compensationSagaPostProcessor.ProcessAsyncRuns compensation in reverse log order for rejected state
Register custom log providerISagaBuilder.UseSagaLog()Replace default in-memory log implementation
Register custom state repositoryISagaBuilder.UseSagaStateRepository()Replace default in-memory state store
Propagate trace context from current ActivitySagaTraceContext.WithCurrentTraceContext on ISagaContextBuilderLinks saga to incoming HTTP/message trace when building context
Propagate trace context from message headersSagaTraceContext.WithTraceContext(traceparent, tracestate)Use when building context from RabbitMQ/Kafka/HTTP headers

Minimal Integration Recipe

Install 

dotnet add package Genocs.Saga

Setup in Program.cs 

using Genocs.Saga;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSaga();

var app = builder.Build();

app.Run();

Message processing usage 

var coordinator = app.Services.GetRequiredService<ISagaCoordinator>();
await coordinator.ProcessAsync(message);

Behavior Notes That Affect Agent Decisions

  • SagaCoordinator serializes processing per saga ID using KeyedLocker to avoid concurrent mutation of the same saga.
  • SagaSeeker merges ISagaAction and ISagaStartAction, then de-duplicates by concrete type.
  • SagaProcessor catches handler exceptions, sets SagaContextError, rejects saga when needed, and still persists state/log.
  • Saga.Reject sets state to Rejected and throws SagaException by design.
  • SagaPostProcessor executes compensation by reading saga logs and replaying messages in descending CreatedAt order.
  • Initial state is created only for ISagaStartAction when no persisted state exists.
  • Saga execution emits OpenTelemetry spans (Saga.Process, Saga.Execute, Saga.Handle, Saga.Compensate) for Jaeger correlation; register Genocs.Telemetry and AddSource(“Genocs.Saga”) is included.

Source-Accurate Capability Map

Registration and saga discovery

  • Registers the saga coordination pipeline services.
  • Provides default in-memory persistence or custom persistence overrides.
  • Scans loaded assemblies and registers saga interfaces with transient lifetime.

Files:

Coordinated execution pipeline

  • Orchestrates message processing through seeker, initializer, processor, and post-processor components.
  • Applies per-saga locking boundary for consistent state transitions.
  • Supports optional completion and rejection callbacks.

Files:

State initialization and persistence updates

  • Reads existing saga state and prevents re-entry for rejected sagas.
  • Creates default saga state and data object for start actions.
  • Persists both state and log records after each message handling pass.

Files:

Rejection and compensation flow

  • Invokes custom rejection callback when saga transitions to Rejected.
  • Loads persisted saga logs and invokes compensate handlers in reverse order.

Files:

Default in-memory persistence implementation

  • Stores saga state and log data in process-local lists.
  • Supports read and write operations through repository/log abstractions.

Files:

Telemetry correlation

  • Emits ActivitySource spans for Saga.Process, Saga.Execute, Saga.Handle, Saga.Compensate.
  • Extracts W3C traceparent/tracestate from ISagaContext metadata when present.
  • SagaTraceContext provides WithCurrentTraceContext and WithTraceContext for cross-service trace propagation.

Files:

Dependencies

From src/Genocs.Saga/Genocs.Saga.csproj:

  • Microsoft.Extensions.DependencyInjection
  • Scrutor
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Persistence.MongoDB Agent Reference
Genocs.Saga.Integrations.MongoDB Agent Reference →