ADR-0004: Base the control plane on golusoris, pinned
- Status: Accepted
- Date: 2026-10-09, accepted 2026-10-13
- Authors: Epitrop maintainers
Context
The Go control plane (architecture) needs configuration, logging, retry, clocks, identifiers, telemetry, an HTTP client and server, server-sent events, an MCP server, health probes, idempotency, canonical JSON and signed receipts. golusoris already ships each of these. Writing them again would break HISS-19 (one behaviour, one implementation).
golusoris publishes two Go modules from one repository, each with its own tags:
github.com/golusoris/golusoris(root), taggedvX.Y.Z.github.com/golusoris/golusoris/core, taggedcore/vX.Y.Z.
Release v0.13.0 and core v0.10.0 were cut from the same commit (f3b3355). The root go.mod at v0.13.0 still requires core v0.9.2 and uses a replace => ./core directive. Go ignores replace in a dependency, so for a consumer that names only the root module, the root's own requirement selects core v0.9.2. That version lacks core/retry, core/codec/jcs and core/tlsx, and httpx/server and grpc at v0.13.0 import core/tlsx. The go command then fails, or looks up the newest core release, which nothing pins. Only an explicit core requirement gives the pair golusoris tested together.
Epitrop keeps no relational database (ADR-001): state lives in an in-memory graph hydrated from Git and an append-only event log.
Decision
go.modrequires both modules directly, at exact versions:github.com/golusoris/golusoris v0.13.0andgithub.com/golusoris/golusoris/core v0.10.0. They move together, as one update.- A capability golusoris ships is taken from golusoris. Epitrop writes only what the gaps section lists.
- Modules that need Postgres, SQLite, Redis, NATS or another external state service stay out (see Excluded modules).
- Existing duplicates move now:
internal/sources/httpfetchbuilds its client withhttpx/client.Newand caps bodies withhttpx/client.ReadAllBounded. It gainsGetWithHeaderfor authenticated sources.internal/sources/litellmgatewaydrops its own copy of the bounded GET and callshttpfetch.GetWithHeader.- The token file and snapshot file reads use
ReadAllBounded. Every deferred close that joined its error now usescore/errors.CloseJoin.
Behaviour kept: no retry and no circuit breaker (zero RetryOptions and BreakerOptions), the same per-call deadlines and byte caps. Behaviour changed:
- An oversized body fails with an error wrapping
client.ErrBodyTooLarge. - A non-positive byte cap is refused instead of accepting an empty body.
- Close errors name the operation.
Tests: TestGet_Boundary and TestGetWithHeader in httpfetch_test.go, TestListModels_ResponseCap in source_test.go.
Module map
Weights are the third-party modules (golusoris modules excluded) in each package's import closure at the pinned pair, measured with go list -deps -f '{{with .Module}}{{.Path}}{{end}}' <package>. "httpx" in issue #30 is a directory, not a package; the rows name its packages.
| Need | golusoris module | Owning go.mod | Used now / planned | Notes |
|---|---|---|---|---|
| Outbound HTTP | httpx/client | root | used now: internal/sources/httpfetch, file reads in litellmgateway and cmd/epitropctl | 25 modules (otelhttp, go-retryablehttp, gobreaker, fx). Retry and breaker off, as before. |
| Close-and-join errors | core/errors | core | used now: httpfetch, litellmgateway, codexlocal, cmd/epitropctl | CloseJoin; 1 module (go-faster/errors). |
| Configuration | core/config | core | planned: cmd/epitrop-server | koanf: files, environment, Kubernetes secret directories, *_FILE; 16 modules. Organisation files under Git (agents, routines, budgets) are domain data for the task-graph store, not process configuration. |
| Logging | core/log | core | planned: cmd/epitrop-server | slog; 26 modules. epitropctl operator output stays plain text on stdout; it is not logging. |
| Retry | core/retry | core (new in core v0.10.0) | used now: internal/eventlog replay (#221) | Capped exponential backoff with jitter on an injected clock; 6 modules. HTTP calls retry through httpx/client RetryOptions, not through core/retry. |
| Clock | core/clock | core | used now: cmd/epitropctl sync | clockwork plus fx; 6 modules. epitropctl sync reads the clock once and passes that time to every source's Fetch (#291). |
| Identifiers | core/id | core | planned: task and event ids | UUIDv7 (time-ordered) and KSUID; 7 modules. |
| Telemetry | otel | root | used now: internal/telemetry, cmd/epitropctl | Heaviest: 59 modules (OTLP gRPC exporters, Prometheus). No-op when no OTLP endpoint is set. httpx/client emits otelhttp spans to the global provider; epitropctl builds the providers with otel.New, so they export once an OTLP endpoint is set. |
| REST server | httpx/server, httpx/router, httpx/middleware | root | planned: cmd/epitrop-server | httpx/server 25 modules, httpx/router 6. |
| Server-sent events | realtime/sse | root | planned: UI event stream | Standard library only. Buffers 16 events per client and drops on overflow; no Last-Event-ID replay (see gaps). |
| In-process pub/sub | realtime/pubsub | root | planned: broker fan-out | LocalBus: synchronous fan-out in the publisher's goroutine, exact topic match, no buffering, standard library only. |
| MCP server | core/mcp | core | planned: internal/mcp | Official MCP Go SDK v1.8.0; stdio and streamable HTTP; 32 modules. |
| Health probes | k8s/health | root | planned: cmd/epitrop-server | /livez, /readyz, /startupz and a drain gate; 26 modules. Does not import the Kubernetes client. |
| Idempotency | idempotency | root | planned, partial: inbound REST requests | Idempotency-Key middleware with MemoryStore or a Epitrop Store (atomic Claim/Commit/Release). Does not cover RT-02 (see gaps). The package compiles its Postgres and Redis stores in, so importing it links pgx, rueidis and gRPC: 51 modules. |
| Canonical JSON | core/codec/jcs | core (new in core v0.10.0) | planned: event-log records | RFC 8785; standard library only. Canonical bytes before an event is hashed or signed. |
| Signed receipts | core/crypto/receipt | core | planned: run receipts | Ed25519 Exit-0 receipts, payload wire-compatible with Praetor's execution receipt; refuses a non-zero exit; 25 modules. |
httpx/extclient was considered for litellm-gateway and rejected. Its APIError puts up to 512 bytes of the response body into the error text, and that source must never surface a gateway reply that can echo a credential. Its 8 MiB cap is also fixed.
Gaps Epitrop writes
golusoris v0.13.0 has no graph store and no event-sourcing log. In Go source, git grep -i -E 'topolog|acyclic|kahn' v0.13.0 -- '*.go' finds a HISS test fixture, a topology comment in ai/tiny/serve/fleet and a recursive-type check in jsonschema; none of them stores a graph. Epitrop therefore writes:
- Task-graph store (
internal/sot, planned): an in-memory directed acyclic graph hydrated from Git files. It rejects a cycle before the graph changes, bounds traversal depth and stages changes with rollback. - Git-backed append-only event log (RT-04). golusoris
auditis an append-only audit trail (actor, action, target) behind a store interface meant for Postgres, with a memory store for tests. It has no Git persistence and no replay into state, so it cannot be the source of truth. The event log may feed it later. - Broker semantics on top of
realtime/pubsub. Issue #30 lists the whole in-process broker as a gap. That is not quite right: the in-process fan-out ships asrealtime/pubsub.LocalBus, and Epitrop uses it through thepubsub.Businterface. Epitrop adds: - log-first publishing: append, then fan out;
- a bounded queue per subscriber (HISS-06);
- cursor replay from the event log, which also serves SSE reconnects with
Last-Event-ID. - RT-02 side-effect ledger: idempotency keys
(task_id, action_type)on outbound side effects, recorded in the event log. golusorisidempotencyguards inbound HTTP and gRPC requests only. - Regular-file guard for operator-supplied files (token, snapshot): open, regular-file check and size check before
ReadAllBounded. golusoriscore/astx.ReadFileBoundedchecks the size with a stat, then reads without a read cap or a regular-file check.
Excluded modules
| Module | Reason |
|---|---|
jobs (River on Postgres; jobs/sqlite) | Relational database (ADR-001). The task graph schedules work. |
outbox (Postgres table, River drainer, outbox/cdc) | Relational database (ADR-001). The event log is the outbox. |
pubsub/nats, pubsub/kafka, pubsub/gcp, realtime/pubsub/redis | External broker or store. Durable history is the Git event log; fan-out is in process. |
jobs/workflow | Needs a Temporal service; the task graph is Epitrop's own. |
idempotency Postgres, Redis and SQLite stores | External or relational store (ADR-001). The REST API uses MemoryStore or a Epitrop Store. |
httpx/extclient | Error text carries response bytes; cap fixed (see Module map). |
Updates and Renovate
Renovate is onboarded (renovate.json, config:recommended). Its gomod manager reads the two require lines and proposes each new tag as a pull request. config:recommended does not know golusoris as a monorepo, so it proposes the two modules separately until a packageRules entry groups them. Treat the two modules as one update:
- group them in one pull request;
- run
go mod tidyafter the bump; - require the repository gates on that pull request.
Root and core releases are cut from one commit, and the root go.mod lags the core version it was tested with (see Context). Without the grouping rule, a consistent update is a manual go get github.com/golusoris/golusoris@<tag> github.com/golusoris/golusoris/core@<core tag> of a release pair, followed by go mod tidy and the gates.
v0.13.0
v0.13.0 is released, so Epitrop starts at v0.13.0. No earlier golusoris code exists here to convert, and the migration plan reduces to that starting point. From docs/migrations/v0.13.0.md, these parts become the starting contract for planned modules:
httpx/client: unsafe methods retry only with anIdempotency-Keyheader orRetry.AllowUnsafe.httpx/server: a zero request-body limit means 10 MiB.realtime/sse: event IDs and names reject carriage return, line feed and NUL, so event-log IDs must be plain tokens.idempotency: a customStoreimplements atomicClaim,CommitandRelease; keys include method, host, target, tenant and an optional principal; capture defaults to 1 MiB.
The golusoris epic for v0.13.0, golusoris/golusoris#429, stays open after the release, with children for dependency substitution, gated verification and governance lockdown. A later release can therefore change transitive dependencies; it arrives through the update path above.
The go line moves from 1.27 to 1.27.2, because both golusoris modules require Go 1.27.2 or later. A Go 1.27.1 toolchain with GOTOOLCHAIN=local refuses the module (go: go.mod requires go >= 1.27.2). Both the golang builder image and actions/setup-go set GOTOOLCHAIN=local, so:
- the
Dockerfilebuilder moves to thegolang:1.27.2-trixieindex digest; ci.ymlreads the version fromgo.mod(go-version-file), assecurity.ymlalready does.
praetor-api.yml asks for stable, which setup-go resolves through the actions/go-versions manifest; it needs that manifest to list Go 1.27.2.
Licence
golusoris code is EUPL-1.2 from v0.9.0 on (LICENSING.md at v0.13.0), the same licence as Epitrop. The licence texts are byte-identical (cmp LICENSES/EUPL-1.2.txt). The third-party modules now built into Epitrop (go list -deps -test ./...) are under MIT, BSD-3-Clause, Apache-2.0 and MPL-2.0 (go-cleanhttp, go-retryablehttp). MPL-2.0 is on the EUPL-1.2 Appendix of compatible licences; the permissive licences carry notice obligations only. No conflict.
Consequences
- Positive: The control plane starts on tested modules for config, logging, telemetry, server, health, MCP and idempotency instead of new code. The catalog sources share one HTTP client stack with OTel spans, ready for retry and a breaker when a source needs them. Oversized bodies are now distinguishable with
errors.Is. - Negative:
- Epitrop's build list grows from zero to 25 third-party modules for the code that exists today; each planned module above adds its weight.
- Importing
idempotencylinks Postgres and Redis drivers that Epitrop never uses. - Two modules must move in step, and golusoris is pre-1.0, so a minor release can break the API (v0.13.0 did).
Revisit triggers
- Revisit when golusoris/golusoris#1011 ships a core-level bounded reader with a regular-file guard: switch the file reads in
litellmgatewayandcmd/epitropctlfromhttpx/client.ReadAllBoundedto that reader, and drop the regular-file guard Epitrop writes (see Gaps Epitrop writes).
Follow-ups
- [x] Inject
core/clockinto the sources andsync: done in #291. - [x] Ask golusoris to move the
idempotencystores into subpackages, so the middleware links no database driver: asked in golusoris/golusoris#818; the stores moved into their own packages in golusoris/golusoris#939, released in v0.18.0. Epitrop importsidempotencynowhere yet. - [x] Ask golusoris for a core-level bounded reader with a regular-file guard, so
ReadAllBoundedneed not come fromhttpx/clientfor file reads: asked in golusoris/golusoris#1011. - [x] Add the Renovate
packageRulesentry that groupsgithub.com/golusoris/golusorisandgithub.com/golusoris/golusoris/coreinto one pull request:renovate.jsongroupgolusoris, done in #291.