core

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

core

CI Release Go Reference Go Report Card Go Version License codecov Mutation

Foundational interfaces for the thesmos ecosystem.

core is a stdlib-only Go module that defines the contract seams every other thesmos library and framework depends on:

  • Clock — abstracts time.Now, time.Sleep, and timers so libraries remain deterministic under simulation and test. Returns Hybrid Logical Clock instants for distributed callers and a stdlib time.Time projection for the common case. Implementations: clock/hlc (production HLC), clock/fake (virtual time). See RFC-0001.
  • Rand — unified randomness seam exposing both Uint64 and Read([]byte). Implementations: rand/pcg (non-crypto PCG), rand/crypto (CSPRNG over crypto/rand), rand/seeded (HMAC-SHA-256 deterministic CSPRNG), rand/fixed (constant for tests). See RFC-0002.
  • Crypto — cryptographic-hash seam producing comparable fixed-shape digests covering 256/384/512-bit outputs in one type, with a stable per-implementation ID and long-term Algorithm identifier so receipts and audit chains survive algorithm rotation. Hash(data), Combine(left, right), and Stream (for inputs that don't fit in memory) cover leaf commitments, Merkle / chain construction, and large-payload hashing. Implementations: crypto/sha256, crypto/sha512 (SHA-384, SHA-512), crypto/sha3 (SHA3-256, SHA3-384, SHA3-512). See RFC-0003.
  • Telemetry — metric and trace seams for hot-path observability emission, with attribute pre-binding via .With([]Attr) keeping the emit path zero-allocation while preserving context.Context for OTel exemplar correlation, baggage, and trace-stitching. Kind-tagged Attr bridges to stdlib log/slog. Implementations: telemetry/noop. See RFC-0004.
  • Epoch — in-process strictly-monotonic 64-bit counter for leader generations, schema versions, optimistic-concurrency tokens. epoch.Epoch value type plus thread-safe epoch.Counter. See RFC-0005.
  • Tag — snapshot-immutable string key/value pairs used in place of map[string]string on value-type structs that cross async-buffered, cached, or cross-goroutine boundaries. See RFC-0006.
  • Version — opaque CAS token (Version), WriteOptions with IfMatch / IfNoneMatch preconditions, and Versioned[T] for read-your-writes optimistic-concurrency loops. See RFC-0007.
  • Page — pagination request (Page with WithDefault helper) and response (Cursor[T]) shape with SliceCursor[T] and MapCursor[K, V] generic helpers. Range-over-func iteration makes "forgot to check err" syntactically impossible. See RFC-0008.
  • ID — fixed-max-size identifier value type (id.ID) covering 128-, 160-, and 256-bit shapes in one comparable type, with four generator subpackages: id/ulid (128-bit time-sortable Crockford base32), id/uuidv4 (128-bit random RFC 4122), id/ksuid (160-bit K-sortable base62 — alphanumeric encoding and 128-bit entropy floor for gov / defense / fintech / health consumers), id/fixed (constant for fixtures). Every subpackage ships Format and Parse for canonical serialization. See RFC-0009.
  • Pool — typed sync.Pool wrappers: Pool[T any] for arbitrary values, ResetPool[T Resettable] that auto-clears state on Put (preventing cross-tenant data leaks at the type level), and NewBufferPool for the *bytes.Buffer case. See RFC-0010.
  • Arena — bump allocator for hot-path variable-length output. Append / Alloc return three-index-capped sub-slices into a contiguous backing buffer; epoch-tagged Marker + SliceSince capture multi-call regions safely. Pool integration via Reset (satisfies pool.Resettable) keeps the backing buffer warm across requests. See RFC-0011.

These interfaces — and the others added over time — share three properties:

  1. Stdlib-only. core has zero non-stdlib imports. The dependency guard fails CI on any new import outside $gostd and the module itself. (ADR-0001)
  2. Single module. One go.mod. Submodules are not needed because there are no heavy deps to isolate. (ADR-0002)
  3. Apache 2.0. Unencumbered for production and downstream redistribution. (ADR-0003)

Status

Pre-1.0. Interfaces are added incrementally as their shape stabilises in consumer libraries. Breaking changes are possible until v1.0.0; once tagged, the standard Go module versioning rules apply.

Install

go get go.thesmos.sh/core

Module path: go.thesmos.sh/core · Repo: github.com/thesmos-ai/core

Documentation

  • ADRs — accepted architectural decisions
  • RFCs — proposals under discussion or accepted as direction
  • Contributing — local setup, conventions, PR flow
  • Security — vulnerability disclosure policy

License

Apache 2.0. See LICENSE and NOTICE.

Documentation

Overview

Package core is the stdlib-only foundation of the thesmos ecosystem.

core defines the contract seams (Clock, Rand, Reporter, …) that every other thesmos library imports. It depends on nothing outside the Go standard library; consumer-specific implementations (OpenTelemetry, Prometheus, crypto/rand, HLC, …) live in consumer repositories such as testkit, thesmos, and space.

The constraints governing this module are documented as Architecture Decision Records under docs/adr/.

Source Files

View all Source files

Directories

Path Synopsis
Package arena provides a contiguous byte buffer for batching variable-length binary output on hot paths.
 Package arena provides a contiguous byte buffer for batching variable-length binary output on hot paths.
Package clock defines the time seam used by every thesmos library.
 Package clock defines the time seam used by every thesmos library.
fake
Package fake provides a deterministic virtual-time clock.Clock for tests.
 Package fake provides a deterministic virtual-time clock.Clock for tests.
hlc
Package hlc provides a production clock.Clock backed by the system wall clock with Hybrid Logical Clock semantics.
 Package hlc provides a production clock.Clock backed by the system wall clock with Hybrid Logical Clock semantics.
Package crypto defines the cryptographic seams used by every thesmos library that constructs digests, audit chains, Merkle accumulators, or content addresses.
 Package crypto defines the cryptographic seams used by every thesmos library that constructs digests, audit chains, Merkle accumulators, or content addresses.
sha256
Package sha256 provides a SHA-256 crypto.Hasher implementation backed by crypto/sha256.
 Package sha256 provides a SHA-256 crypto.Hasher implementation backed by crypto/sha256.
sha3
Package sha3 provides SHA3-256, SHA3-384, and SHA3-512 crypto.Hasher implementations backed by crypto/sha3 (Go 1.24+).
 Package sha3 provides SHA3-256, SHA3-384, and SHA3-512 crypto.Hasher implementations backed by crypto/sha3 (Go 1.24+).
sha512
Package sha512 provides SHA-384 and SHA-512 crypto.Hasher implementations backed by crypto/sha512.
 Package sha512 provides SHA-384 and SHA-512 crypto.Hasher implementations backed by crypto/sha512.
Package epoch defines Epoch, a strictly-monotonic 64-bit counter type used for leader generations, schema versions, optimistic concurrency tokens, and any other "before/after" tag a system needs to reason about ordering across time.
 Package epoch defines Epoch, a strictly-monotonic 64-bit counter type used for leader generations, schema versions, optimistic concurrency tokens, and any other "before/after" tag a system needs to reason about ordering across time.
id
Package id defines ID, the fixed-max-size identifier value type used across the thesmos ecosystem for time-sortable and random-collision-resistant identifiers, plus the Generator interface that produces them.
 Package id defines ID, the fixed-max-size identifier value type used across the thesmos ecosystem for time-sortable and random-collision-resistant identifiers, plus the Generator interface that produces them.
fixed
Package fixed provides an id.Generator that returns the same id.ID on every call.
 Package fixed provides an id.Generator that returns the same id.ID on every call.
ksuid
Package ksuid provides an id.Generator producing K-Sortable Unique Identifiers — 160-bit time-sortable identifiers with a 4-byte Unix-second timestamp prefix and a 16-byte random payload.
 Package ksuid provides an id.Generator producing K-Sortable Unique Identifiers — 160-bit time-sortable identifiers with a 4-byte Unix-second timestamp prefix and a 16-byte random payload.
ulid
Package ulid provides an id.Generator producing ULIDs — Universally Unique Lexicographically-Sortable Identifiers.
 Package ulid provides an id.Generator producing ULIDs — Universally Unique Lexicographically-Sortable Identifiers.
uuidv4
Package uuidv4 provides an id.Generator producing RFC 4122 version-4 UUIDs (122 random bits + 4 version bits + 2 variant bits).
 Package uuidv4 provides an id.Generator producing RFC 4122 version-4 UUIDs (122 random bits + 4 version bits + 2 variant bits).
Package page defines Page and Cursor — the pagination request and response shape used by every list-returning interface so unbounded scans are impossible to write accidentally.
 Package page defines Page and Cursor — the pagination request and response shape used by every list-returning interface so unbounded scans are impossible to write accidentally.
Package pool provides typed sync.Pool wrappers for hot-path allocation pressure relief.
 Package pool provides typed sync.Pool wrappers for hot-path allocation pressure relief.
Package rand defines the randomness seam used by every thesmos library.
 Package rand defines the randomness seam used by every thesmos library.
crypto
Package crypto provides a rand.Rand backed by crypto/rand.
 Package crypto provides a rand.Rand backed by crypto/rand.
fixed
Package fixed provides a constant-output rand.Rand for tests that need to assert against a specific randomness branch.
 Package fixed provides a constant-output rand.Rand for tests that need to assert against a specific randomness branch.
pcg
Package pcg provides a PCG-backed rand.Rand suitable for non-cryptographic randomness.
 Package pcg provides a PCG-backed rand.Rand suitable for non-cryptographic randomness.
seeded
Package seeded provides a deterministic CSPRNG-quality rand.Rand for simulation and unit tests.
 Package seeded provides a deterministic CSPRNG-quality rand.Rand for simulation and unit tests.
Package tag defines Tag and Tags — the string key/value pair shape used in place of [map][string]string on value-type structs that cross async-buffered, cached, or cross-goroutine boundaries.
 Package tag defines Tag and Tags — the string key/value pair shape used in place of [map][string]string on value-type structs that cross async-buffered, cached, or cross-goroutine boundaries.
Package telemetry defines the metric and trace seams used by every thesmos library that needs to emit observation signals from a hot-path code path.
 Package telemetry defines the metric and trace seams used by every thesmos library that needs to emit observation signals from a hot-path code path.
noop
Package noop provides a telemetry.Reporter that discards every signal it receives.
 Package noop provides a telemetry.Reporter that discards every signal it receives.
Package version defines Version, the opaque, monotonic per-(scope, key) version token used by reads and writes for read-your-writes and compare-and-swap semantics.
 Package version defines Version, the opaque, monotonic per-(scope, key) version token used by reads and writes for read-your-writes and compare-and-swap semantics.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.