Skip to content

Effectus v0.3.0

Effectus v0.3.0 adds supported integration kits for embedded Go services and standalone business executors. It also moves the public Go module to the canonical GitHub repository path.

Integration kits

Embedded Go library

The new embedded package provides a small checked-runtime API.

  • Register fact type samples, rule sources, and invocation-aware verb handlers with one builder.
  • Compile one checked generation during application startup.
  • Execute requests through runtime.Engine with a namespace and idempotency key.
  • Reject a repeated identity when its facts change.
  • Keep fact samples out of runtime defaults.

The default embedded ledger and outbox are process-local. Use effectusd with PostgreSQL when executions must survive a process or host restart.

Standalone business executor

The new executorhttp package validates the Effectus HTTP invocation contract and writes explicit protocol outcomes.

It requires execution, saga, effect, attempt, direction, idempotency, argument-hash, and contract-hash metadata. Business handlers can return success, retryable, permanent, stale-fence, or unknown outcomes.

The standalone order-review example runs these components:

  • effectusd with a checked bundle.
  • PostgreSQL for durable Effectus state.
  • A separate PostgreSQL-backed business executor.
  • Transactional destination idempotency checks.
  • Duplicate admission and business-row assertions.
  • Rendered demonstration credentials with CI coverage for non-default values.

v0.3 Go compatibility

Published v0.3.0 does not contain the frozen v0.3 compatibility imports. Version 0.4.0 introduces them without a separate compatibility module or tag. See the compatibility guide for the import paths and release verification procedure.

Runtime corrections

  • Nested admission facts now flatten in stable key order.
  • An explicit dotted fact path takes precedence when the same admission also supplies a nested representation.
  • Embedded fact samples provide compiler type information but do not become runtime data.
  • The executor HTTP boundary now rejects a missing saga ID.
  • The PostgreSQL polling integration tests use fixed, isolated test tables instead of dynamic SQL identifiers.
  • The MinIO and MinIO client development images update x/crypto, x/net, and x/text to resolve CVE-2026-56854.

Documentation and validation

  • The Integration Guide compares embedded and standalone deployment models.
  • The examples index links to both runnable order-review paths.
  • CI executes the embedded example and the complete standalone Docker Compose stack.
  • CI builds and scans the standalone business-executor image.
  • Protobuf compatibility validation has an exact, one-time allowlist for the public Go package migration. Other compatibility changes still fail the check.

Breaking changes

The public Go module path changes from:

github.com/effectus/effectus-go

to:

github.com/josephjohncox/effectus

Update Go imports and module requirements before adopting this release:

go get github.com/josephjohncox/effectus@v0.3.0
go mod tidy

The protobuf go_package options also use the new module path. Regenerate downstream Go protobuf bindings when they depend on these options.

The old module path does not redirect to the new module. Versions 0.2.1 and earlier remain available under their published source and artifact tags.

Database migration

Version 0.3.0 adds no database schema migration. Existing v0.2.1 PostgreSQL schemas remain current.

Before deployment:

  1. Back up Effectus state and test the restore path.
  2. Update Go consumers to the new module path.
  3. Build and test business executors against the v0.3.0 invocation contract.
  4. Deploy one immutable checked bundle and daemon version.
  5. Verify readiness, generation digests, recovery metrics, and destination idempotency behavior.

Do not run old and new daemon versions against one execution workload unless the destination contracts and deployment procedure explicitly support it.

Remaining external assumptions

  • External destinations must enforce the supplied idempotency key or fencing grant.
  • executorhttp adapts the protocol. Operators must add service authentication and enforce fencing where required.
  • Multi-tenant destinations must include tenant identity in checked verb arguments and business keys when business identifiers are not globally unique.
  • Operators must provide PostgreSQL high availability, backups, capacity limits, monitoring, and tested recovery.
  • A trusted ingress or service mesh must provide production TLS and network policy.
  • Kafka DLQ publication and source-offset commit remain non-transactional and can duplicate a DLQ record after a crash.
  • OCI verification still requires an operator-provided verifier and trust policy.