Glossary

These definitions match current go-sequent behaviour and the locked decisions. Framework and API names stay in English.

A–C

Aggregate / AggregateRoot

The consistency boundary. Embed aggregate.Base. Change state only in appliers. Command methods call Apply after validating. Loaded and committed through the Repository and UnitOfWork. Never share across goroutines. See AggregateRoot.

AfterCommit

Hooks registered with workflow.RegisterAfterCommit. They run only after a successful commit, for notifications and other non-ledger side effects. A hook failure does not undo committed events. See Workflow.

AuthZ

Authorization at the command boundary: security.Authorizer, installed with WithAuthorizer. A denial returns ErrDenied. It is separate from authentication. The event store has a hash chain and no event signatures. See AuthZ.

Command

An intent to change the system. It has a CommandType, an optional AggregateID, and Meta, and may implement Validate. It enters through CommandService.Execute, which runs middleware, AuthZ and the handler. See Command.

Compensating event

A new domain event that offsets or corrects earlier facts without rewriting history. Used for business corrections, and together with tombstones for GDPR-style scrubbing in projections.

E–H

Event

A past-tense fact with a type name and an envelope (aggregate id, sequence, time). It is stored, then drives projectors and workflows. Decoded through event.Registry. See Event.

EventStore

Persists command records and aggregate streams. Enforces OCC and unique keys, and keeps a per-aggregate hash chain. Implementations: memory and postgres. Applications usually go through the Repository. See EventStore.

Hash chain

Integrity mechanism. Each event stores prev_hash and event_hash, a SHA-256 over canonical fields (formula in eventstore/hashchain). The chain is per aggregate stream, and the genesis prev_hash is 32 zero bytes. It is verified on load and by VerifyChain. It detects tampering. It is not an event signature. It adds cost on append and on load.

L–M

Ledger projection

A read model for balances and ledgers. It updates inside the write transaction (SyncInTxn), so read-your-writes holds after commit. The bank BalanceProjector is the demo, in memory. In production, persist through SQL. See Projector.

Meta (command metadata)

command.Meta: CommandID, TenantID, UserID, IdempotencyKey, correlation and causation ids, Source, AuthContext and more. AuditOf builds an audit snapshot.

Money (decimal)

types.Money: a decimal amount and a currency. The JSON amount is a string. float64 is banned. See Money.

O–P

obs / OpenTelemetry

Optional write-path telemetry: latency, outcome, OCC conflicts, optional outbox depth. It is not the business audit source. The application owns the providers. See OpenTelemetry.

OCC (optimistic concurrency control)

Append requires ExpectedVersion to equal the stream tip, otherwise ErrOptimisticConcurrency. obs can count conflict storms. See Unique keys and OCC and Write-path consistency.

Outbox

Transactional outbound message rows, drained by polling a Postgres table. Ledger projectors stay on SyncInTxn. The outbox is for asynchronous and external side effects. See Publisher.

partition_key

A partition hint on aggregates and streams, often from tenancy.PartitionKey. Used for physical partitioning or unique-key scoping inside a shared schema. It does not mean schema-per-tenant. See Partitioning.

Projector / projection

A publish.Handler, optionally with ManagedTables, that updates read models. Registered on SyncInTxn and invoked after append and before commit. A failure rolls back the write transaction. Rebuild uses PublishProjectorsOnly, which skips workflows. See Projector.

R–S

Read-your-writes

After a successful write, the same client reads that update. SyncInTxn gives this for ledgers: the balance projection updates in the same transaction, before the commit returns.

Snapshot

A JSON fold of aggregate state to speed up loads: snapshot plus later events. snapshot.Snapshotter can take them in the background. See Snapshotting.

SyncInTxn

The publish mode: projectors, then workflows, run inside the write transaction. Required for ledger projections. See Publisher.

T–W

Tenant vs User

Meta.TenantID is the multi-tenant isolation unit. Meta.UserID is the actor. Do not trust a client UserID alone; use AuthContext and AuthZ. Tenancy middleware copies the tenant from the context. For Circle multi-merchant, the tenant is the onboarded merchant and the user is a buyer or operator under that merchant. Do not assign one TenantID per end user. See Tenancy.

Tombstone

The GDPR strategy: emit marker events such as gdpr.SubjectTombstoned, and have projectors scrub or stop serving personal data. The product path is not crypto-shredding.

Unique keys

UniqueKeys map scope → value, such as a tenant-scoped owner. A database unique violation becomes ErrUniqueKeyViolation. See Unique keys and OCC.

Idempotency

Key space (TenantID, IdempotencyKey). A successful retry is a no-op by default, and Strict returns ErrReplay. Stores: memory and postgres. See Idempotency.

UnitOfWork (context-scoped)

A per-Execute identity map on the context. Add and Load reuse one instance. Commit collects uncommitted events in load order. Never share across goroutines. See Repository.

Upcaster

Transforms old event payloads on load (event/upcast). It is not a way to import a Ruby Sequent database. See Event evolution.

Workflow

An event orchestration handler registered with RegisterWorkflow. It runs on SyncInTxn but is excluded from projection rebuild. It may register AfterCommit hooks. See Workflow.

Docs track the go-sequent library. When APIs drift, the source wins.