Independent libraries and tools
Surefold is a collection of independently useful libraries and engineering tools. Kotlin/JVM libraries sit alongside an operations console and tools for checking code changes. Use the piece your project needs.
Separate dependencies and releases. Core is published as Lark; the naming change is pending.
Surefold Core · structured concurrency
fun summary(id: UserId): Either<SummaryError, Summary> = attempt {
timeout(2.seconds) {
parZip(
{ users.find(id) ?: fail(UserNotFound(id)) }, // blocking JDBC
{ orders.recent(id) }, // blocking HTTP
) { user, recent -> Summary(user, recent) }
}
}parZip runs the calls in parallel. A failure interrupts the sibling; the scope waits for both forks to end. At the deadline, timeout requests cancellation.
Interruption is cooperative: work that ignores it can keep the scope waiting beyond two seconds.
Libraries and engineering tools
Each project works on its own. Integrations connect them when you want to use them together.
Structured concurrency · published as Lark
Structured concurrency and typed errors are the foundation. Core also supplies application wiring, resilience policies, typed streams, actors, persistence, clustering, Kafka and service testing as separate modules.
Use Core on its own. Typed errors use Lark’s own Fail and Either API; current examples require a source build.
HTTP APIs, clients and contracts
Describe an endpoint, including its failures, as a Kotlin value. Interpret it as a route, an OpenAPI document, a typed client or an MCP tool.
No Core dependency. Choose your backend and codec; 1.0.0 ships Pekko HTTP and Jackson. Jetty is on snapshots.
Load testing and performance measurement
Schedule arrivals, measure response time including late departures, and check whether the generator kept up. Keep a slow service separate from a saturated load generator.
Test any service. No Core or Pelican dependency unless you choose a specific integration.
Compile-time object mapping
Map domain objects to DTOs, rows or messages. A K2 compiler plugin generates constructor calls and collection loops, or reports the fields it cannot fill at compile time.
Use it in an existing Kotlin/JVM build. No Core dependency and no reflection-based mapping engine.
Service operations across existing tools
Bring a service’s alerts, metrics, logs, deployments, owner and runbook onto one page. Follow the links back to the monitoring and deployment systems that supply them.
Runs as its own application and can watch services written with any stack. No Core dependency.
Verification for AI-written code
Run the project’s checks, flag weakened tests and protected configuration edits, and surface the review a change needs. Keep the verification boundary visible before merging.
A standalone CLI and GitHub integration. No Core dependency; agent hooks currently support Claude Code.
The Core toolkit
Lark, becoming Surefold Core, covers the work around a blocking call too. Start with one dependency and add the modules that give the service its structure.
Real applications
Two working examples of the libraries together. Their integration choices are examples, not requirements for your service.
Core · Pelican · Proofload · Kimney · Estate · Gauntlet
A pet shop with a typed HTTP API, an actor-owned catalogue, a Postgres outbox, optional Kafka delivery and a SolidJS front end. Service tests start the application graph in-process.
Estate watches the local demo’s operational signals; Gauntlet reports on changes using a shadow-mode policy.
The hosted shop uses a fake backend for browsing. The repository contains the JVM service, infrastructure and load tests, and currently uses library snapshots.
Core cluster · Pelican · Proofload
A demonstration bank across four Kotlin and Scala services. Accounts are actors on a three-node cluster; transfers are sagas backed by an event journal.
The documented chaos run cuts nodes, freezes Kafka and stops databases under load, then checks the ledger. Read the scenario and results with the code.
Evidence and limits
Virtual threads, Lark, Reactor and Pekko compared on bounded I/O, real sockets, overload and CPU work. Read the results, the trade-offs and where each model wins.
A mixed HTTP workload ramped towards 50,000 arrivals/s on one laptop shared with the generator. Refused arrivals make it a void run, not proof of sustained capacity. Explore the recorded data and methodology.
The Core tests check that interruptible work has ended before a timeout returns. The guide explains the boundary for work that ignores interruption.
Response time, service time, schedule lateness and generator saturation answer different questions. Proofload documents how each is measured.
Pick a project. Follow its installation instructions and run its first example.