golib is a multi-module Go library monorepo for explicit, composable service infrastructure. Public modules live under pkg/, retain independent semantic versions, and use module paths such as github.com/faustbrian/golib/pkg/jsonrpc.

The repository favors standard-library contracts, visible control flow, bounded resource use, and strict compatibility over framework magic. Packages can be adopted independently; using one does not require adopting the rest.

The Golib design language defines the shared construction, lifecycle, ownership, error, security, and interoperability contract. The cohesion baseline records the measured module families, current divergences, and pre-v1 remediation decisions.

• Use jsonrpc for typed internal RPC and command-oriented service calls where JSON-RPC 2.0 is the protocol contract.
• Use jsonapi for externally consumed resource APIs that need JSON:API relationships, sparse fields, pagination, extensions, and errors.
• Use service, router, and http-middleware for explicit net/http services.
• Use queue for durable asynchronous work and queue-control-plane for operational visibility.
• Use postgres, migrations, outbox, and idempotency for durable persistence workflows.
• Use the focused resilience packages through the resilience architecture guide; policy order, deadlines, retry safety, and local versus distributed state remain explicit.
• Use wire, tabular, xsd, and wsdl for bounded serialization and document processing.

The package catalog groups independently releasable libraries and adapters by the problem they solve. The exhaustive engineering inventory also records internal tools, fixtures, examples, interoperability harnesses, and benchmarks. See the documentation index, choosing packages, and recommended stacks for audience paths, combinations, and tradeoffs.

The fastest executable introduction is the HTTP and JSON-RPC service recipe. Use the durable worker or external integration recipe for those boundaries. All modules are unreleased; the recipes run from this workspace and do not imply public availability or production readiness.

Install the version from .go-version, then run:

make inventory
make cohesion
make specification-decisions
make docs MODULES=.
make workspace-test MODULES=pkg/clock
make check MODULES=pkg/jsonrpc
make conformance MODULES=pkg/jsonrpc
make api-update MODULES=pkg/jsonrpc
make ci-changed BASE=origin/main

MODULES accepts a comma-separated list of exact module directories. Changed selection expands through reverse owned dependencies. make ci runs the full repository contract. api-update intentionally refreshes a module's pinned export baseline after a reviewed compatible API change. Specification conformance and independent-implementation interoperability are separate attributable gates. The repository-wide specification governance contract defines mandatory decision records, provenance, executable evidence, and review. The root documentation gate validates structure, navigation, spelling against the reviewed project dictionary, and every local and external link.

Every releasable module must pass isolated tests with GOWORK=off, race and fuzz checks, exact per-production-package 100% statement coverage, and 100% mutation efficacy and mutant coverage. Missing tools, empty reports, skipped services, stale manifests, and absent results fail closed. NilAway is advisory but must run and may not regress silently.

The root CI workflow invokes the same scripts as local development. Package-local workflows are intentionally unsupported. Full policies are documented in quality, CI, performance engineering, and security. Repository-wide security review starts with the threat model, security matrix, and residual-risk register. The generated source documentation audit tracks objective package and exported API comment gaps without treating comment counts as a substitute for technical review.

Modules are released independently with directory-prefixed tags such as pkg/jsonrpc/v1.0.0. Every module's first public release is stable v1.0.0; the internal v0.0.0 version exists only for unpublished source-proxy checks. Owned dependency releases follow the dependency graph in modules.json. See release policy and the current operational-assurance verdict.

• Contributing
• Compatibility
• Deprecation
• Security
• Support
• Code of conduct
• Engineering policy

Repository tooling is MIT licensed. Each independently releasable module retains its own LICENSE and third-party notices.