Go 1.27 concurrency foundations: deterministic cleanup and handoff,
bounded fan-out, request coalescing, and retry/circuit-breaker policies —
built on Go 1.27 generic methods, with a go vet analyzer that catches
leaked handles before the code runs.
go get github.com/apsis-io/velocity@v0.8.2Status: v0. Requires Go 1.27. The API is deliberate but young — it has no
consumers outside the author's own projects, and it will change where real use
says it should. That is a weaker statement than it looks: reports from those
projects are good evidence that a shape causes a real failure, and no evidence
at all that anyone wants a new API, so nothing here should be read as a request
for features. Every design decision and its reasoning is recorded in
docs/decisions.md.
| you have | use |
|---|---|
| a resource whose cleanup must run exactly once, at a known time | ownership |
| a bounded set of connections, buffers, or handles to reuse | pool, with Stats() for the reuse rate |
| N tasks or a collection to run concurrently, bounded | async |
| many concurrent callers wanting the same expensive result | dedupe |
| a flaky dependency to retry or stop calling | resilience |
| work to start now and be told about later, not waited on | Runner.Submit, traits.Future, or Owner.MutateAsync |
| a condition to poll until it holds, bounded by a context | resilience.RetryUntil |
| a lock whose wait has to be cancellable | async.Mutex, async.RWMutex |
| fan-out where the result does not matter | async.ForEachFuncs |
| a daemon that should converge to a declared state and stay there | teleos — level-triggered invariant convergence, its own module |
Every package follows the same rules: nothing waits except under the
caller's context; errors are typed and errors.Is to sentinels; callbacks
return normally; instrumentation is a Hooks struct the caller supplies,
not metrics the package keeps. (teleos below is its own module with its
own contract: a status report, not error sentinels.)
ownership decides when cleanup runs and makes transfer between goroutines
explicit. Its borrow checks are an assertion layer: View and Mutate report
a conflicting access at once as ErrConflict, never waiting, so a borrow in
this package cannot deadlock on another. It is not Rust ownership and not a
mutex — use a plain defer Close() or an async.RWMutex where those are the
right tool.
conn := ownership.NewCloser(rawConn) // Drop is Close
defer conn.Close()
cfg := ownership.Own(config) // no Drop; borrow-checked
name, err := cfg.View(func(c Config) (string, error) { return c.Name, nil })
err = cfg.WithWrite(func(c *Config) error { c.Retries++; return nil })A missed defer Close() is a leak, so a Drop-bearing value is backed by a
net: if every handle becomes unreachable without a release, the net runs the
Drop. It is a backstop, not a second lifetime — the runtime promises no
cleanup before program exit — and the full contract is in
docs/ownership.md.
The shapes that pay for themselves:
-
Scopeunwinds a multi-step construction that fails partway, so each acquisition no longer closes everything opened before it:scope := ownership.NewScope() defer scope.Close() // LIFO, continues past failures, errors joined conn, err := dial(); if err != nil { return nil, err } _ = scope.OwnCloser(conn) raw, err := dial(); if err != nil { return nil, err } // Close releases conn _ = scope.OwnCloser(raw) scope.Disarm() // the bundle owns them now return &Bundle{conn, raw}, nil
-
Leasefor resources identified by a value — permits, IP allocations — enforcing release-exactly-once and use-after-release. -
Frozenpublishes a value read-only by type: there is noMutateto call.Viewer[T]/Mutator[T]put the same guarantee in any signature. -
Seal/Drainedretire a value other goroutines are still reading without waiting inside the package:owner.Seal() select { case <-owner.Drained(): case <-ctx.Done(): return ctx.Err() } return owner.Release()
-
Maptransforms an owned value into another type while chaining Drop (flush the writer, then close the file).Detachis the one exit that skips Drop, named for what it does to cleanup responsibility. -
MutateAsync/WithWriteAsyncrun a mutation on its own goroutine and hand back atraits.Future, with the write borrow queued rather than refused:mutation := owner.WithWriteAsync(ctx, func(c *Config) error { c.Retries++; return nil }) // ... elsewhere, whenever: _, err := mutation.Await(ctx) // the work's outcome, or the wait's error
ctxbounds the wait for the borrow, so cancelling stops a mutation that has not started. A Future can be dropped: the work still completes and still releases. Re-entering the cell from inside the callback reportsErrConflictas usual — except a nestedMutateAsyncwhose Future the callbackAwaits, which waits for a borrow the callback itself holds. That is a caller waiting inside a critical section it owns, and a deadline turns it into an error where the caller is already looking.A submitted mutation is counted separately from a borrow (
State.Pending), andReleaseand every transfer (Move,Detach,IntoShared,Freeze,Map) refuse withErrConflictwhile one is outstanding. A submission is not a borrow — no address is exposed and nothing is excluded by it — so without a count of its own, ending or transferring a handle was a race the caller could not see: theDropor transfer could run while the mutation was still queued, surfacing later as a file descriptor that outlives its owner or aFuturefailing withErrMoved. Ending a handle is therefore a choice — await the mutation and release, orSealto discard it deliberately and have the submission reportErrSealed:mutation := owner.MutateAsync(ctx, mutate) result, err := mutation.Await(ctx) // drain, then: err = owner.Release() // or owner.Seal() to drop it on purpose
Model, invariants, and the "when not to use this" list:
docs/ownership.md. Full API:
docs/ownership-cheatsheet.md.
ocaml_of_go — a pure-Go OxCaml
compiler and register VM — backs its OxCaml 'a iarray (immutable array) with
a Frozen[[]Value]: the slice is published read-only by type, so no
Mutate even exists to call by mistake.
That design is what turned a latent bug into a loud one. Five of the VM's
Array.* builtins reached past the wrapper with a bare type assertion:
in := args[0].Obj.([]Value) // panics: Obj is *Frozen[[]Value]For a boxed array that assertion succeeds; for an iarray it cannot, so the
program died with interface conversion at the exact builtin that would
otherwise have read — or, for Array.set, silently mutated — a
published-immutable slice. The type error everyone sees at the boundary is
the point: bypassing Frozen is not a convention violation you discover as a
data race in production, it is a crash at the instruction that lies. The fix
collapsed the hand-rolled Frozen dance in every builtin into one generic
viewer, and mutation of an iarray became a clean error instead of a success:
// one helper per package, not seven copies of the borrow/unborrow ritual
func viewArrayElems[R any](v Value, fn func([]Value) (R, error)) (R, error) {
if v.Kind == KindIArray {
return v.Obj.(*Frozen[[]Value]).View(fn)
}
return fn(v.Obj.([]Value))
}
n, err := viewArrayElems(args[0], func(s []Value) (int64, error) { return int64(len(s)), nil })Array.set on an iarray now reports Invalid_argument("Array.set: iarray is immutable"). Without the wrapper the same code would have compiled, run, and
mutated — which is the difference between read-only by type and read-only
by convention.
The analysis module (separate go.mod, so the library does not
depend on x/tools) ships lostrelease, a go vet analyzer modelled on
lostcancel: a Borrow, BorrowMut, NewLease, or pool.Get handle that
is discarded, or has a path to a return on which it is never released, is
reported at the acquisition and at the return.
go install github.com/apsis-io/velocity/analysis/cmd/velocityvet@v0.2.0
go vet -vettool=velocityvet ./...Inside this checkout, build it from the tree instead: just lint does that
for every module here.
It learns what to track from the code rather than from a list it carries. A function that hands back something the caller must release says so at its own declaration:
// Borrow acquires an advanced shared read borrow.
//
//velocity:acquires
func (o *Owner[T]) Borrow() (*ReadBorrow[T], error)Go treats that as a directive, so godoc hides it. The analyzer publishes it as a package fact, which reaches consumers — who see velocity through export data and never its comments. Any library can mark its own handle-returning functions and get the same checking; nothing about the mechanism is velocity-specific.
Production Borrow carries no runtime safety net — a leaked borrow blocks
its cell deterministically rather than being reclaimed at some GC-chosen
moment. Under -tags=velocitydebug a leak is logged through slog and
released so tests keep going.
A bounded set of made, held, and returned resources. A Checkout is an
ownership.Lease, so use-after-return and double return are caught, and it
is an io.Closer a Scope can own. With and pool.Use acquire a checkout,
pass the resource to the callback, and release it when the callback returns.
clients, err := pool.New(pool.Config[*Client]{
New: dial,
Close: func(c *Client) error { return c.Close() },
Max: 8,
})
checkout, err := clients.Get(ctx) // waits for capacity under ctx
defer checkout.Release() // or checkout.Discard() if it turned out broken
client, err := checkout.Value()
// Or scoped to a callback:
resp, err := pool.Use(ctx, clients, func(ctx context.Context, client *Client) (*Response, error) {
return client.Do(ctx, req)
})A Runner states a concurrency policy once — an explicit Limit (there is
no implicit "unbounded" default) and optional Hooks — and every operation
runs through it.
run, err := async.New(async.Limited(8), async.WithHooks(hooks))
outcomes, err := run.Gather(ctx, async.Named("a", fetchA), async.Named("b", fetchB))
outcomes, err = run.GatherFuncs(ctx, fetchA, fetchB) // unlabeled
first, err := run.FirstSuccess(ctx, tasks...) // Race for first completion
results, err := run.Map(ctx, items, process) // fixed pool of Limit workers, []R in order
err = run.ForEach(ctx, items, visit)Gather returns outcomes in source order with every error joined. Map
returns a bare []R; failures travel out of band as one *ItemError{Index, Err} per failed item in the joined error, and a failed item's slot is the
zero value. Broadcast fans one owned value out to workers under concurrent
read borrows; Pipeline chains typed stages via a generic Then[R]; Group
wraps sync.WaitGroup.Go with panic recovery.
ForEachFuncs is GatherFuncs for functions that produce only an error, and
mirrors the Map/ForEach pair a collection already has — the common case is
work whose result is collected somewhere else, and the alternative is writing
func(context.Context) (struct{}, error) and discarding a slice of outcomes.
ErrGroup.GoContext is Go with the permit wait bounded by a context, and it
reports whether the function was submitted. Go blocks for a permit with a
plain send, which is the right trade for a submitter that has work it must run;
a consumer reading from a channel is the other case, and with every permit held
by a function ignoring its own cancellation, a Go loop cannot reach its own
cancellation branch and so never reaches WaitContext either. False means the
group was already finished, or finished while the submitter waited — and either
way the function never ran, so cleanup it was meant to perform belongs in
Hooks.OnTaskComplete rather than inside the function.
Runner.Submit is the same idea without the group: start one task, get a
*traits.Future[R] back, ask whenever.
f := run.Submit(ctx, fetch) // *traits.Future[Response]
// ... elsewhere, whenever:
result, err := f.Await(ctx) // the work's outcome, or the wait'sDropping the handle is safe — the work runs and resolves it for anyone watching
— and a panic or a runtime.Goexit in the function arrives as a failed Result
rather than as a dead process, because a submitted task panics somewhere its
submitter has already left. It is for a handful of tasks written out by hand; a
collection wants Map or Gather. Note the Limit does not bound it: a limit
applies to the tasks of one operation, and a one-task operation has none to
bound, so Submit starts a goroutine per call.
async.Mutex and async.RWMutex are locks whose acquire waits under the
caller's context, which sync.Mutex and sync.RWMutex cannot do. RWMutex
gives writers priority so a stream of readers cannot starve one. It costs about
7x sync.RWMutex uncontended — 85 ns and one 48-byte Permit against 12 ns
and none — which is worth it only when a goroutine can genuinely be parked on
the lock and something needs it to stop.
run.ErrGroup(ctx) is errgroup.WithContext with the pieces it lacks:
eg, ctx := run.ErrGroup(ctx) // Limit from the Runner; bounds goroutines
for _, item := range items {
eg.Go(func(ctx context.Context) error { return process(ctx, item) })
}
err := eg.Wait() // first error; siblings were cancelled on iterrgroup |
async.ErrGroup |
|
|---|---|---|
| context | closed over | passed to each function |
| limit | SetLimit per group |
stated once on the Runner |
| a panic | crashes the process (or re-panics in Wait) |
recovered into a *Panic error |
| after the first failure | later functions still run | not run |
| all errors | first only | Wait first, Errors() all, in order |
| a function that ignores cancellation | Wait hangs |
WaitContext(ctx) bounds it |
| instrumentation | none | Hooks see wait and run time |
| typed results | index bookkeeping by hand | Gather / Map |
| cost, 8 functions | 3.2 µs / 20 allocs | 3.4 µs / 12 allocs; at a limit of 4, 4.8 vs 4.8 |
Two things errgroup gave implicitly that the replacements do not:
- One error at a boundary.
Mapjoins an*ItemErrorper failure, which is more information than a 1 KB status field wants when every item failed for the same reason.ErrGroup.Waitis first-error-only; forMap,async.Failures(err)[0]is the lowest failed item. - Every submission runs.
errgroupran every function it started, so cleanup inside a function for state set up outside it was unconditional.Mapdoes not run an item never claimed after cancellation, andErrGroupdoes not run a function that gets its permit after the first failure. Cleanup for state registered before the fan-out therefore belongs inHooks.OnTaskComplete(whichMapfires for unclaimed items with the cause) or in a sweep after the call, not inside the function.
sync.Mutex cannot be locked under a context, which is what
x/sync/semaphore.NewWeighted(1) usually stands in for. async.Mutex and
async.Semaphore wait under the caller's context and hand back a Permit
that is released exactly once; a permit that is not released is reported by
lostrelease, including the Try forms' ok branch.
held, err := mu.Lock(ctx)
if err != nil {
return err
}
defer held.Release()Group[K, V] coalesces concurrent calls per key: one runs, every caller
gets the result. The zero value works; New takes options. A caller that
leaves does not cancel the work unless it was the last one — and even then
the key stays registered until the callback returns, so a callback that
ignores its context never stacks: a later caller waits for it and takes its
value if it succeeded, or starts afresh if it failed.
group, err := dedupe.New[string, Report]()
report, err := group.Do(ctx, "report-42", func(ctx context.Context) (Report, error) {
return fetchReport(ctx, 42)
})The context fn receives is the round's and is cancelled when the round
completes, so a value that keeps doing I/O after Do returns (a lazy
handle, a stream) must not be built from it.
DoBatch runs one function over several keys; DoBorrowed loans an owned
input to the round. When the result is a resource, configure
WithResultDrop and use DoShared: every caller gets a counted
*ownership.Shared[V], and Drop runs once, after the last release.
Singleflight is an alias for readers who know the pattern by that name.
The vocabulary the other packages share: the two function types a resource's lifecycle is described in, and the two types that carry the outcome of work.
type Drop[T any] func(value T) error
type Clone[T any] func(value T) (T, error)ownership and dedupe take the same Drop[T], so a result's cleanup is
described once whether it came from a cell or a round.
type Result[R any] struct{ Value R; Err error } // the outcome of work
type Future[R any] struct{ ... } // a handle on work, not yet finishedResult and Future are separate types on purpose. "Not finished" is a
property of the handle, not of the outcome, so an unresolved Future has no
Result at all rather than a Result holding a sentinel that means "wait".
Try() (Result[R], bool)— the second return is readiness, so unknown, succeeded and failed are three different answers rather than one error channel.Await(ctx) (R, error)— the error reports whichever applies: the work's failure, or the context's cause when the wait ended first.
Giving up on the wait does not give up on the work. It still completes, the
handle still resolves for anyone watching, and nothing needs cleaning up by
whoever let go — which is what makes a Future droppable without thought.
Two more types are shared for the same reason. Panic is what a recovered
panic becomes — the value and the stack, as an error — so a panic in one
callback of a fan-out is a failed item rather than a dead process, and
errors.As finds it from any package. ErrCallbackExit is the neighbouring
case: a callback that ended without returning (runtime.Goexit) reported
success by every other signal, because the deferred release ran and the
goroutine simply stopped. ConfigError names the option a constructor refused,
and one definition serves every package, so "which option was refused" reads
the same everywhere.
Future earns its place here by having more than one producer —
Owner.MutateAsync and Runner.Submit — which is the bar Result cleared
with dedupe.DoBatch.
backoff, err := resilience.ExponentialBackoff(100*time.Millisecond, 5*time.Second, 0.2)
value, err := resilience.Retry(ctx, resilience.Policy{MaxAttempts: 5, Backoff: backoff}, fetch)
breaker, err := resilience.NewBreaker(resilience.BreakerPolicy{
Trip: resilience.FailureRatio(0.5, 20),
OpenFor: 30 * time.Second,
Failure: func(err error) bool { return !errors.Is(err, context.Canceled) },
})
value, err = breaker.Do(ctx, fetch) // errors.Is(err, resilience.ErrOpen) when trippedA tripped breaker rejects immediately and recovers on the clock; nest it
inside Retry with ErrOpen classified as not retryable. ManualClock
makes tests of either deterministic.
RetryUntil is for work that is "until this is true" rather than "until this
succeeds" — a lock that is held, a socket that answers, a process that is gone.
Its probe reports whether the condition held, so there is no sentinel error to
invert and nothing to invent for a probe with no value to return:
value, err := resilience.RetryUntil(ctx, resilience.UntilPolicy{
MaxAttempts: 0, // 0 means the context is the bound
Backoff: backoff,
}, func(ctx context.Context) (string, bool, error) {
v, err := tryTakeTheLock(ctx)
return v, err == nil, err // (value, holds, fatal error)
})Every give-up in this package is a *RetryError satisfying
errors.Is(err, resilience.ErrGaveUp) — the attempts exhausted, the context
ending the loop, and a backoff sleep the context interrupted. The earlier split
into two error types meant the answer a caller received depended on whether the
attempt count or the deadline happened to bind first, which is arithmetic the
caller wrote rather than the situation they were in.
Policy.MaxAttempts == 0 means the caller's context is the bound. A derived
count — attempts = budget/interval + 1 — binds first and ends the loop up to
one interval short of the budget, silently; a policy that bounds nothing is
ErrInvalidPolicy wrapping ErrNoBound.
Hedge is the tail-latency counterpart of Retry: Retry waits for an
attempt to fail and cannot help one that is merely slow, while Hedge
starts the next attempt while the previous is still running, so p99 falls
toward p50. The first success wins and the rest are cancelled.
value, err := resilience.Hedge(ctx, resilience.HedgePolicy[*Response]{
MaxAttempts: 3,
Delay: backoff, // the same Backoff Retry uses
Budget: budget, // caps the extra load hedging creates
Discard: func(r *Response) error { return r.Body.Close() },
}, func(ctx context.Context, attempt int) (*Response, error) {
return client.Fetch(ctx, request)
})Discard disposes the losing results a hedge inherently produces: N
attempts return one, so the rest leak unless something closes them. Not
every hedging library omits this — faustbrian/go-hedge has a Disposer
and velocity took the idea from it — but failsafe-go does, and where a
library treats the result as opaque the cleanup has to be written out a
second time. When the result is owned, Discard is simply its Drop. Budget is the other half — a dependency slow enough to trigger
hedging is the last one that should receive several times its usual load, so
each execution credits the budget and each speculative attempt spends a
credit.
Delay can be measured rather than guessed: NewLatencyDelay(0.95, …)
hedges an attempt once it exceeds the p95 of recent successful ones, so
"too slow" tracks what the dependency has actually been doing.
resilience is three policies, not a resilience framework, and that is the
whole of it. failsafe-go
covers much more — timeout, fallback, rate limiting, bulkhead, adaptive
concurrency and throttling, HTTP and gRPC integrations — is actively
maintained, and is the better choice when breadth is what you want. velocity
does not try to catch up with it.
What failsafe-go cannot express is that a result may own something. Every policy that discards a result leaks it when the result is a connection, a lock, a file handle, or filesystem artifacts such as a temp directory and the blob inside it: a hedge drops N−1 results, a retry with a result predicate discards one that arrived perfectly well, a fallback drops the primary's, a timeout returns before a result that arrives anyway. That is not a bug in failsafe-go — a library that treats the result as opaque cannot know that dropping one costs something.
The failsafeown module supplies the missing half. Make the
result an *ownership.Owner[T], which carries its own Drop, and whatever
the policy chain does not hand back is released:
exec := failsafe.With(
fallback.NewWithResult(spare),
hedgepolicy.NewWithDelay[*ownership.Owner[*Conn]](50*time.Millisecond),
)
conn, err := failsafeown.Get(ctx, exec, dial, failsafeown.Hooks[*Conn]{})
// every connection the chain dialled and dropped is closedGetWithExecution is the same thing for attempts that are not
interchangeable, which for a hedge is the common case since replicas
usually have addresses — racing a peer against an origin needs to know
which attempt it is:
policy := hedgepolicy.NewBuilderWithDelay[*ownership.Owner[*Layer]](0).
// Without this, failsafe cancels the race on ANY result, so the arm
// that fails fastest ends the one that would have succeeded.
CancelIf(func(_ *ownership.Owner[*Layer], err error) bool { return err == nil }).
Build()
owner, err := failsafeown.GetWithExecution(ctx, failsafe.With(policy),
func(e failsafe.Execution[*ownership.Owner[*Layer]]) (*ownership.Owner[*Layer], error) {
if e.IsHedge() {
return fetchFromRegistry(e.Context())
}
return fetchFromPeers(e.Context())
}, hooks)Counting attempts in the closure instead works only while nothing else in
the chain also reruns fn; add a retry and the counter silently stops
meaning what it did.
Use IsHedge, not Hedges, to tell the arms apart. Hedges is a count
shared by every attempt — "how many hedges exist", in-progress ones
included — so with a short delay both arms read the same number, both take
the same branch, and the branch nobody took never runs. That is a hang
rather than a wrong answer, and it does not reproduce under a long delay,
because then the primary reads the counter before the hedge exists.
It is a separate module, so the library itself keeps no dependency on failsafe-go.
teleos is a separate module — own go.mod, own tag,
teleos/v* — for a different shape of problem: a long-running process that
should converge to a declared resting state and stay there. Level-triggered
invariant convergence: an invariant is a pure function from an observation
to two facts — is this slice of reality at rest, and if not, what data
effects would move it toward rest.
engine := teleos.New(teleos.Config[World, Effect]{
Plan: []teleos.Invariant[World, Effect]{net, mounts, process},
Names: []string{"NetworkReady", "MountsReady", "ContainersReady"},
})
report := engine.Step(observe()) // observe: reality into a struct
if report.Status == teleos.Frontier {
apply(report.Want) // data effects; then observe again
}Plan serialises — slice order is dependency order. Concurrent runs
independent stages in one pass. Chain is for resources that both acquire
and release: the acquire sweep runs root to leaf, the release sweep leaf to
root, so deleting the pod stops the process before the netns it lives in
disappears — no phase flags, the direction of every pass comes from the
chain itself.
The engine is what the loop's failure modes meet, and its bounds are
counted in operations, never time: a per-pass effect cap (a plan that never
stops emitting is a wedge, and a wedge is never handed to an executor), a
pass budget, stall detection through a caller-supplied state oracle, and
A-B-A oscillation detection. Terminal diagnoses are idempotent data, and
Reset is the human's decision. converge runs the
loop on velocity's runtime: wake-driven passes, Runner batches with a
barrier, dedupe coalescing, and effects as opcodes.Instruction through
an opruntime.Table.
It was evaluated before it was released: perigeos's coordinated-checkpoint
barrier controller — a hand-rolled four-phase state machine — re-expressed
as one plan, with its no-outage property asserted structurally
(barrier_eval_test.go). Full model, engine
contract, and the honest note about what the closures are:
teleos/README.md.
Head-to-head numbers against the libraries these packages drew from —
x/sync, go-singleflightx, resenje.org/singleflight, hunch, conc —
with fairness rules and an honest account of where velocity is slower and
why, live in benchmarks/README.md.
Package-level costs, measured (ownership, after the lazy-broadcast
optimization): the scoped paths — View, Mutate — are allocation-free
at ~41–43ns; construct-and-release is one allocation at ~104ns; the
advanced borrow tier keeps its documented per-borrow allocations, on
purpose — it is the explicit, auditable tier. teleos's engine Step is
~78ns converged, ~120ns at an open frontier, and its harness is pure.
Every number here is reproducible from the in-module benchmarks; the
benchmark job compiles them in CI so they cannot rot.
The rest of the survey (measured, and left as they are on purpose):
ErrGroup.Go is at par with x/sync's (~1.1µs, same allocs); Gather's
one-goroutine-per-task cost is its documented trade against Map's fixed
pool — Map wins per-task cost by construction, and the benchmark pairing
exists to show it; pool's 2 allocations per checkout are the safety model
itself (Checkout with its embedded Lease, and the release closure —
use-after-release detection and discard semantics are what those bytes
buy); dedupe's ~6 allocations per
round front a call expensive enough to be worth deduplicating, and they buy
the owned-result handles, the hooks, and the panic capture. Production
numbers from the two deployments running v0.10.0 are in
docs/decisions.md: no resident library goroutines,
zero mutex contention, and the pool amortizing to near-zero at rest — its
counters re-arm whenever the consumer's migrations recreate identities,
so the long-run reuse-rate is the number to re-read, not the first day
after a re-arm.
Both consumers are the author's own projects, which is the honest scope and a weaker one than independent adoption would be. What they establish is that the shapes work against real workloads and fail legibly when they do not — not that anyone outside would want them.
Each has also declined something, which is worth more than the adoptions:
Periapsis wrote a full registry swap onto ownership.Owner — Seal, Drained,
the sealed table wired to real behaviour — and reverted it, because a registry
admits by queuing and Mutate refuses. Its reason is recorded in the code, and
it argues from this repository's own no-wait invariant. That is the package's
sharpest limit stated by someone who had read the reasoning rather than skimmed
it.
Periapsis, a virtual-kubelet fork, ported seven call sites to velocity and
has tracked each release since, and uses ownership.Owner to carry a Drop
through a failsafeown chain. It exercises ownership, async (Runner.Map,
ErrGroup, Mutex, and now RWMutex — deployed to its cluster and measured
there), dedupe, and failsafeown, and dropped conc, x/sync/singleflight
and x/sync/errgroup on the way. It is on v0.8.2, the current tag, so it has
the fix that made a queued mutation visible to Release. What is running on
its cluster may lag the pin; the pin is what this repository can see.
breeze, a Go daemon, took resilience first: four hand-rolled poll loops
became one pollUntil on RetryUntil, and the report that prompted
RetryUntil is recorded below. It then adopted ownership.Scope for a
four-branch unwind in tryBindDaemon, and measured the cost of that choice. It
is on v0.5.1, and it takes velocity/analysis v0.1.0 as a tool dependency —
it runs velocityvet over its own tree, which is the point of the analyzer
being a separate module.
Most of what changed in v0.2.0 and v0.3.0 came from the Periapsis port, and the reports were measured rather than impressionistic:
dedupeholding an abandoned round's key until its callback returns took a ping loop from 10 in-flight calls per second to 1, matching whatx/sync/singleflightdoes for a callback that ignores its context.- The zero-value
dedupe.Groupexists because a partial struct literal holding one compiled and then nil-panicked on the first uncached call, wheresingleflight.Grouphad worked uninitialised for years. failsafeown.GetWithExecutionexists because the module could not express a hedge racing a peer against a registry — the case its own documentation led with.async.Mutex's benchmark note is that consumer's measurement, including the part that says the end-to-end difference was below run-to-run variance.
The same port also corrected this repository's claims more than once, and
docs/decisions.md records which were wrong and why
rather than quietly restating them.
velocity imports no tracer and keeps no metrics. Instrumentation is two mechanisms the caller owns, and together they are span support:
Hooks — the packages that time work publish it. async.Hooks. OnTaskComplete fires in the task's own goroutine with the index, label,
permit-wait, duration, and outcome — before the handle resolves, so closing
a span there is not racing the awaiter. dedupe.Hooks carries the round's
lifecycle: OnJoin with its leader flag (where a joining caller's span
links) and OnComplete with duration and outcome (the round's End).
Context transparency — every API passes the caller's context to its
callbacks, so the span opened at the call site is already inside the work.
Wrap any unit — a Runner task, a converge observe or apply, an
ownership borrow's release — and it is traced.
Two subtleties are load-bearing:
- A
dedupejoin links; it does not parent. A round's execution deliberately outlives its callers, so its context derives from the group's base context (WithBaseContext), not from whichever caller led the round. A joining caller's span is a link to the execution's span, and caller context values are invisible tofnunless set on the base. - The drop net fires without a context. Its Drop runs on a runtime goroutine from an unreachable cell, so any span it emits is a root span — which is exactly right: a root span named "dropnet" is a leak report, not a request flow.
And a cost note: a span around teleos's Step would cost more than the
step. The pass's units — observe and apply — are your callbacks; wrap those.
just check # fmt, vet + staticcheck, wsl, lint (lostrelease), test, race, velocitydebug, examples
just fuzz # ownership state-machine model, 30s
just bench # in-module benchmarks
just bench-comparejust is optional; each recipe is a plain go command listed in the
justfile.
Copyright 2026 Malformed C. Licensed under the Apache License, Version 2.0; you may not use these files except in compliance with it. See LICENSE for the terms and NOTICE.md for the attributions — velocity is an independent implementation informed by several libraries, none of whose source it bundles.