core

Foundational interfaces for the thesmos ecosystem.

core is a stdlib-first 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). UTCSource returns a UTC reading with a bound on its error, and clock/kernel reads the bound from the Linux kernel. See RFC-0001 and RFC-0036.
• 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/constant (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 computes a content address. HashTagged and CombineTagged hash the leaves and interior nodes of a tree or chain under a one-byte role whose high bit gives the arity, so a leaf hash cannot equal a node hash. Stream hashes inputs that do not fit in memory. Implementations: crypto/sha256, crypto/sha512 (SHA-384, SHA-512), crypto/sha3 (SHA3-256, SHA3-384, SHA3-512). See RFC-0003 and RFC-0029.
• HMAC — keyed-authentication peer of the hash seam. crypto.MAC mirrors crypto.Hasher's shape (same Digest output, same ID + Algorithm model, same Stream) with first-class constant-time Verify and a Digest.ConstantTimeEqual helper for streaming verification. Implementations: crypto/hmac/sha256, crypto/hmac/sha512 (HMAC-SHA-384, HMAC-SHA-512), crypto/hmac/sha3 (HMAC-SHA3-{256,384,512}). See RFC-0012.
• Sign — asymmetric-signing seam. crypto/sign.Signer / Verifier split (verifier-only consumers don't construct a signer), KeyID value type with canonical per-algorithm derivation, optional StreamingSigner / StreamingVerifier capability interfaces for hash-then-sign algorithms. Implementations: crypto/sign/ed25519 (Ed25519 PureEdDSA per RFC 8032 §5.1.6), crypto/sign/ecdsap384 (ECDSA P-384 + SHA-384 per FIPS 186-5, ASN.1 DER signatures, also satisfies the streaming interfaces), crypto/sign/mldsa (ML-DSA-44, ML-DSA-65 and ML-DSA-87 per FIPS 204, with the context string fixed per signer). SignContext bounds a signer that crosses a process boundary with a context. Resolver builds a verifier from a stored algorithm name out of a table the caller writes, and Policy requires valid signatures from k of n parties, counting each key once. See RFC-0013, RFC-0033, RFC-0035 and RFC-0039.
• Framer — unambiguous domain separation for hashed and signed inputs. Domain (name + version) plus a Framer builder that length-prefixes every part, so no two distinct inputs can encode to the same bytes. HashDomain is built on it. See RFC-0016.
• AEAD — authenticated-encryption seam. crypto.AEAD embeds stdlib cipher.AEAD and adds the same ID + Algorithm identity model as the hash and signing seams, so a ciphertext at rest records what produced it. Seal / Open helpers carry the nonce with the ciphertext. Implementation: crypto/aesgcm (AES-128-GCM, AES-256-GCM). See RFC-0017.
• Keeper — key-custody seam. Keeper wraps and unwraps data keys without exposing the root key, with optional Destroyer and KeyGenerator capability interfaces. The shape is the one a KMS or HSM already has, so a consumer swaps custody without touching call sites. Destroy schedules the destruction of a wrapping key and returns the time at which it becomes irreversible. Implementation: crypto/localkey (in-process, for development and tests). See RFC-0018 and RFC-0034.
• XOF — extendable-output-function seam. crypto.XOF / XOFStream produce arbitrary-length output for key derivation and deterministic padding, where a fixed-size Digest cannot. Implementation: crypto/shake (SHAKE128, SHAKE256). See RFC-0019.
• 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. Propagator / Carrier carry a SpanContext across a process boundary, with MapCarrier for the common case. Implementations: telemetry/noop, telemetry/w3c (W3C Trace Context traceparent / tracestate). See RFC-0004 and RFC-0020.
• 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. Admissible and Watermark admit a write whose fence epoch is at or above the scope's watermark, and ErrFenced reports revoked authority. See RFC-0005 and RFC-0026.
• 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. A Version proves identity, never order. See RFC-0007 and RFC-0026.
• 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/constant (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 byte buffers, whose pool.Buffer zeroes its whole capacity on Reset. Bounded[T] is the fixed-capacity peer for objects that are scarce rather than merely reusable — a connection, a decoder, a hardware handle — where exhaustion must be reported (ErrLimit) rather than allocated around. See RFC-0010 and RFC-0021.
• 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.
• Errs — error-classification seam: a closed eight-value taxonomy of what a caller should do about a failure, not what went wrong. Classify walks an error tree zero-allocation and recognises stdlib sentinels, so a producer that has never heard of the package still classifies usefully; Retryable is the shorthand a retry loop or a circuit breaker asks for. See RFC-0015.
• Resilience — the algorithms every caller of a remote dependency needs: Breaker (per-target circuit, single-probe half-open, injectable failure judgement for transports where failure is not an error), Bulkhead (concurrency limit with optional queue, rejection / timeout / cancellation kept distinct), and Retrier (attempt count and a sliding-window budget, full-jitter Backoff). All read time through clock.Clock, so their transitions are exact under a virtual clock. See RFC-0023.
• Batch — request coalescing: Loader[K, V] accumulates concurrent single-key loads into one batched call and deduplicates concurrent loads of the same key. Not a cache — results are not retained past the in-flight window. See RFC-0024.
• Fixed — fixed.Fixed64, a decimal at eight places stored as one int64. Add, Sub, Mul and Div return an error on overflow instead of wrapping. The text form renders all eight places and round-trips exactly, and the package has no conversion from float64. See RFC-0025.
• CAS — content-addressed storage. A cas.Store is bound to one hasher. Put verifies that the data hashes to its address, stores nothing when it does not, and reports exactly one write per address under concurrency. cas.Store has no Delete. Implementation: cas/memory. See RFC-0027.
• Blob — named object storage, streamed in both directions, with conditional writes through the version vocabulary. A failed Put leaves the key as it was, an open reader returns one version of the object, and a listing walked to the end over an unchanging store returns every object once. Implementation: blob/memory. See RFC-0028.
• Conformance — coretest/castest and coretest/blobtest check any store against the rules of its package, across a restart and a crash when the adapter supplies them. Core's tests run each suite against a broken store for every case. cas.AsStreamer, crypto.AsDestroyer and the other As functions find a capability behind decorators that implement Unwrap, or UnwrapKeeper for a crypto.Keeper. See RFC-0038.
• Task — structured concurrency: All, Each, Map, Stream and Run return only after every goroutine they started has returned. The first error cancels the other tasks and is the result, and a task that panics crashes the process from its own goroutine. Each, Map and Stream run on a fixed set of workers and do not allocate per element. Every calls a function repeatedly with a delay and jitter between calls, and Quorum returns as soon as k of n calls succeed. See RFC-0030 and RFC-0037.
• FSM — finite state machines over small integer states and events. A Spec is a transition table, built once and validated at construction: unreachable states, states that cannot be left and edges that can never be taken are errors. Allows checks a stored status change before a compare-and-swap, and a Machine runs guards and exit, edge and entry actions for one event at a time. Neither allocates per event. See RFC-0031.
• Tlog — the Merkle tree of RFC 9162 over any crypto.Hasher, stored as the 256-hash tiles of C2SP tlog-tiles. With SHA-256 the bytes match RFC 6962, so C2SP witnesses verify the tree. Builder integrates batches of leaves with at most 96 KiB of state, and ProveInclusion and ProveConsistency build a proof from one batched read of at most two tiles per level. Hashing, verification and integration into a reused Update do not allocate. See RFC-0032.

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

1. Stdlib first. Production code imports the Go standard library, the module itself, and golang.org/x modules that have no module requirements, each listed by name in the dependency guard. The guard fails CI on any other import. Test code may draw on a closed allow-list. Extending either list takes an ADR. (ADR-0015)
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. The primitive set is chosen for coherence of the layer model rather than per-item demand, and lands incrementally. Breaking changes are possible until v1.0.0; once tagged, the standard Go module versioning rules apply. (ADR-0005)

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.