BatchWeaver is a proof-gated batching compiler and typed request-coalescing runtime for Go. It finds supported scalar access patterns—including common N+1 query shapes—proves their safety conditions, previews deterministic changes, and executes compatible calls in bounded batches without silently crossing request, tenant, authorization, transaction, or session boundaries.
Release status:
v1.0.1is the current stable release. The Tier 1 Go API is frozen under Semantic Versioning;bridgeand theadapters/*packages are explicitly experimental, and compiler artifact schemas remainv1alpha1. Artifacts are checksummed and reproducible but not signed. See the release notes, the API freeze, and the stable-release decision, which records the accepted risks this release ships with.
Hand-written batching can reduce backend round trips, but changing scalar code can also change evaluation order, error identity, cancellation, deadlines, result mapping, and isolation. BatchWeaver treats those behaviors as proof obligations rather than implementation details.
- Proof before transformation. Unknown or unsupported behavior is rejected.
- Overlay before mutation. Scan, proof, plan, diff, build, and test can run without changing source files.
- Typed library contracts. Generic requests, outcomes, providers, and declarations avoid reflection in application-facing code.
- Explicit isolation. Scope and partition contracts keep incompatible work out of the same batch.
- Fail-closed release tooling. Checksums, SBOMs, provenance, compatibility, and publication gates are verified separately from publishing.
- No hidden telemetry. Workload profiles exclude raw keys, payloads, credentials, tenant identifiers, and source.
BatchWeaver does not promise that every Go call can be batched or that batching always improves performance. Unsupported patterns remain scalar or are rejected with a diagnostic.
Go 1.26.x is the tested support window: 1.26.0 is the minimum and 1.26.5 is the current pinned release toolchain.
Install the CLI or add the typed library at the immutable beta version:
go install github.com/Voskan/BatchWeaver/cmd/[email protected]
go get github.com/Voskan/[email protected]For a source checkout at the same version:
git clone https://github.com/Voskan/BatchWeaver.git
cd BatchWeaver
git checkout v1.0.1
make build
./bin/batchweaver version
./bin/batchweaver doctorPackage documentation and import examples are available through pkg.go.dev. See Using BatchWeaver as a Go module for the library and CLI installation paths.
Declare a scalar function and its compatible batch provider with one typed, statically discoverable value:
package users
import (
"context"
batchweaver "github.com/Voskan/BatchWeaver"
"github.com/Voskan/BatchWeaver/operation"
)
type User struct {
ID int
Name string
}
func loadUser(ctx context.Context, id int) (User, error) {
// Scalar implementation.
return User{ID: id}, nil
}
func loadUsers(
ctx context.Context,
req batchweaver.BatchRequest[int],
) (batchweaver.BatchResponse[User], error) {
values := make([]User, req.Len())
for i, item := range req.Items() {
values[i] = User{ID: item.Key}
}
return batchweaver.OrderedOutcomes(req, values)
}
var GetUser = batchweaver.MustDeclareFunction(
operation.MustNewSpec(
operation.MustParseID("users.get"),
operation.ReadOnly(),
operation.WithOrderedResults(),
operation.WithRequestScope(),
),
loadUser,
loadUsers,
)This declaration does not start goroutines, register global state, or mutate source. The runtime API is opt-in; see the runtime guide and the compile-tested declaration example.
# Inspect supported commands and validate configuration.
batchweaver help
batchweaver config validate --file examples/configuration/batchweaver.yaml
# Discover and prove candidates without modifying source.
batchweaver scan ./...
batchweaver prove ./...
# Review a deterministic plan and diff.
batchweaver transform plan ./...
batchweaver transform diff ./...
# Test transformed code through an overlay.
batchweaver test -- -race ./...Materialization is a separate, explicit operation with backup, recovery, and revert support. Start with the verified batching tutorial.
flowchart LR
A["Go source and config"] --> B["Package loading and static analysis"]
B --> C["Semantic proof obligations"]
C -->|"proven"| D["Versioned transformation plan"]
C -->|"unknown or unsafe"| R["Reject with diagnostic"]
D --> E["Preview and build overlay"]
E --> F["Transformed tests"]
F -->|"explicit approval"| G["Optional materialization"]
E --> H["Typed bridge and runtime"]
H --> I["Partitioned batch provider"]
The compiler is conservative: proof certificates are versioned, source anchors are checked before use, transformed builds use overlays by default, and the runtime validates provider outcomes before returning them to callers.
Read the architecture overview, package boundaries, and safety model.
- typed operation, request, response, partition, scheduling, retry, and fallback contracts;
- explicit request-scoped runtime coalescing with bounded queues, independent cancellation, deadlines, deduplication, memoization, and result validation;
- Go package loading, SSA, conservative call-graph/effect analysis, candidate discovery, and deterministic reports;
- semantic proof certificates and static loop-prefetch/runtime-lowering transformations through build overlays;
- exact/composite-key PostgreSQL read synthesis with bounded at-most-one joins,
compile-checked SQL binding overlays,
database/sql, Redis mapping, explicit HTTP/OpenAPI batching, GraphQL wave analysis, and gRPC contracts; - typed pgx v5, go-redis v9, gqlgen, and grpc-go integration packages on the default branch, with pgxmock, miniredis, public-extension, and bufconn tests;
- privacy-safe adaptive analysis, fairness, overload control, recursive waves, and bounded shadow/active tuning;
- standalone LSP, optional gopls proxy, VS Code extension, and a secure workspace daemon with bounded shared analysis caching for CLI/editor requests;
- deterministic release archives, checksums, SPDX/CycloneDX SBOMs, local provenance, compatibility reports, and non-publishing release verification.
bridgeand the fouradapters/*client packages are experimental: they ship in thev1module but are not covered by thev1compatibility promise, because they track third-party client APIs.- Release artifacts are checksummed, SBOM-documented, and reproducible, but they are not cryptographically signed and carry no hosted build attestation.
- Client integrations are covered by hermetic fakes, not by live PostgreSQL or Redis Cluster acceptance runs.
- SQL synthesis is limited to documented exact/composite-key PostgreSQL reads and one explicitly at-most-one INNER/LEFT join; writes, one-to-many joins, and arbitrary SQL rewrites are rejected.
- GraphQL/gRPC optimization requires explicit integrations; arbitrary network request fusion is not inferred.
- Compiler and runtime artifact schemas remain
v1alpha1; they are regenerated rather than migrated and are excluded from thev1API promise. - Linux, macOS, and Windows hosted builds pass on the corrected release branch.
- The VS Code extension is supplied as a GitHub Release VSIX, not through the Visual Studio Marketplace.
- Checksums are published, but the beta has no cryptographic tag or artifact signature; see the release notes and verification instructions.
See known issues and the detailed limitations index.
- Documentation website
- Runnable examples
- Go API and CLI
- Implemented features and v1 readiness
- Documentation index
- Tutorials
- How-to guides
- Reference
- Architecture
- Compatibility
- Security
- Support
- Contributing
make fmt-check
go test ./...
go test -race ./...
go vet ./...
make checkRelease assurance is non-publishing:
make release-snapshot
./bin/batchweaver release verify dist/release-manifest.jsonv1.0.0 freezes the Tier 1 public Go API under Semantic Versioning and ships a
tested upgrade path from every published prerelease. It ships with explicitly
accepted risks — unsigned artifacts, hosted compatibility evidence not observed
at the tagged commit, a short public prerelease period, and no live-backend
acceptance — each recorded with a remediation plan in the
stable-release decision and the
machine-readable gate report.
The project does not claim long-term production-stability evidence. See beta evidence and the continuation plan.
Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.