pkg/

directory
v1.0.0-beta.155 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: MIT

README

Util

Utility packages providing common functionality across the SemStreams platform.

Overview

The util package contains a collection of utility subpackages that provide common, reusable functionality used throughout the SemStreams codebase. Each subpackage focuses on a specific utility domain, maintaining clear separation of concerns.

Subpackages

timestamp

High-precision timestamp utilities for temporal operations and synchronization.

import "github.com/c360/semstreams/pkg/util/timestamp"

Key features:

  • Microsecond precision timestamps
  • RFC3339 formatting with microseconds
  • Time comparison utilities
  • Clock synchronization helpers
  • Temporal indexing support

See timestamp README for detailed documentation.

Architecture

The util package follows a subpackage organization pattern where:

  • Single Responsibility: Each subpackage handles one specific utility domain
  • No Cross-Dependencies: Utility subpackages don't depend on each other
  • Zero External Dependencies: Utilities rely only on Go standard library where possible
  • Performance First: Utilities are optimized for high-frequency use

Usage Pattern

Utility subpackages are imported directly by packages that need specific functionality:

import (
    "github.com/c360/semstreams/pkg/util/timestamp"
)

// Use timestamp utilities
now := timestamp.Now()
formatted := timestamp.Format(now)

Design Decisions

Subpackage Organization: We organize utilities into subpackages rather than a flat structure because:

  • Prevents util from becoming a "junk drawer" of unrelated functions
  • Makes dependencies explicit and trackable
  • Allows utilities to evolve independently
  • Improves code organization and discoverability

Minimal Dependencies: Utilities minimize external dependencies to:

  • Reduce coupling across the codebase
  • Improve testability
  • Ensure predictable performance
  • Simplify deployment and compilation

Guidelines for New Utilities

When adding new utility subpackages:

  1. Single Purpose: Each subpackage should have one clear purpose
  2. No Business Logic: Utilities should be domain-agnostic
  3. Well Tested: Minimum 90% test coverage with edge cases
  4. Documented: Complete API documentation with examples
  5. Performance: Benchmark critical paths

License

MIT

Directories

Path Synopsis
Package acme provides ACME client functionality for automated certificate management
 Package acme provides ACME client functionality for automated certificate management
Package buffer provides generic, thread-safe buffer implementations with various overflow policies.
 Package buffer provides generic, thread-safe buffer implementations with various overflow policies.
Package cache provides generic, thread-safe cache implementations with various eviction policies.
 Package cache provides generic, thread-safe cache implementations with various eviction policies.
Package context provides building blocks for context construction in agentic systems.
 Package context provides building blocks for context construction in agentic systems.
Package dispatch provides two bounded-concurrency substrate primitives:
 Package dispatch provides two bounded-concurrency substrate primitives:
Package errs provides standardized error handling patterns for SemStreams components.
 Package errs provides standardized error handling patterns for SemStreams components.
Package fusion is the generic deterministic-fusion engine: fan-out sub-query dispatch, dedup, rank, and budget enforcement over a GraphQueryClient, plus the product-supplied Lens SPI (lens.go).
 Package fusion is the generic deterministic-fusion engine: fan-out sub-query dispatch, dedup, rank, and budget enforcement over a GraphQueryClient, plus the product-supplied Lens SPI (lens.go).
fusionnats
Package fusionnats is the production NATS implementation of fusion.RetrievalClient (ADR-062 increment "B2"): it wires the engine's resolve/expand/status surface onto the existing public graph query subjects so the lens-driven fusion engine can run against a live graph.
 Package fusionnats is the production NATS implementation of fusion.RetrievalClient (ADR-062 increment "B2"): it wires the engine's resolve/expand/status surface onto the existing public graph query subjects so the lens-driven fusion engine can run against a live graph.
fusionvocab
Package fusionvocab is the production implementation of fusion.RankSignals (ADR-062 increment 5, gh#396): it wires the lens engine's ranking signals onto the vocabulary registry (predicate salience) and the BFO/CCO subclass helper (ontology specificity).
 Package fusionvocab is the production implementation of fusion.RankSignals (ADR-062 increment 5, gh#396): it wires the lens engine's ranking signals onto the vocabulary registry (predicate salience) and the BFO/CCO subclass helper (ontology specificity).
lensregistry
Package lensregistry holds the explicit, instance-scoped registry of fusion Lens factories (ADR-062 increment 3).
 Package lensregistry holds the explicit, instance-scoped registry of fusion Lens factories (ADR-062 increment 3).
Package gateddag is the pure decision brain of gated-DAG dispatch (ADR-046 Phase 2).
 Package gateddag is the pure decision brain of gated-DAG dispatch (ADR-046 Phase 2).
Package graphview provides a shared read-side fan-out primitive over a NATS KV bucket (ADR-081): ONE WatchAll feeding one validated in-memory current-state projection, coalesced to a view-rate tick and fanned out to N local subscribers with snapshot+delta consistency, per-subscriber at-most-once backpressure, and an honest degraded-path contract.
 Package graphview provides a shared read-side fan-out primitive over a NATS KV bucket (ADR-081): ONE WatchAll feeding one validated in-memory current-state projection, coalesced to a view-rate tick and fanned out to N local subscribers with snapshot+delta consistency, per-subscriber at-most-once backpressure, and an honest degraded-path contract.
Package lifecycle provides a substrate convention layer for workflow-shaped entities — named instances with declared phases, restart recovery, operator visibility, and rule integration.
 Package lifecycle provides a substrate convention layer for workflow-shaped entities — named instances with declared phases, restart recovery, operator visibility, and rule integration.
Package logging provides slog handlers for structured logging with multi-destination support, NATS publishing, and graceful fallback behavior.
 Package logging provides slog handlers for structured logging with multi-destination support, NATS publishing, and graceful fallback behavior.
Package ownership implements the ADR-056 authoritative-semantic-state owner registry: the framework substrate that names exactly one owner per (entity-ID pattern, predicate group) and rejects two owners selecting the same cell in an owning write mode.
 Package ownership implements the ADR-056 authoritative-semantic-state owner registry: the framework substrate that names exactly one owner per (entity-ID pattern, predicate group) and rejects two owners selecting the same cell in an owning write mode.
Package platform holds the platform-identity struct used across the SemStreams codebase.
 Package platform holds the platform-identity struct used across the SemStreams codebase.
Package projection implements the ADR-056 Decision 6 graph projection contract — the missing middle layer between "what type is flowing" (the payload registry) and "who may author these facts at runtime" (pkg/ownership).
 Package projection implements the ADR-056 Decision 6 graph projection contract — the missing middle layer between "what type is flowing" (the payload registry) and "who may author these facts at runtime" (pkg/ownership).
Package resource provides utilities for monitoring resource availability.
 Package resource provides utilities for monitoring resource availability.
Package retry provides simple exponential backoff retry logic for transient failures.
 Package retry provides simple exponential backoff retry logic for transient failures.
Package revlag provides a revision-lag "caught up" watermark for async, write-driven, lagging pipelines fed by a NATS KV watch (ADR-066).
 Package revlag provides a revision-lag "caught up" watermark for async, write-driven, lagging pipelines fed by a NATS KV watch (ADR-066).
Package rulepack owns the process-level identity contract for composed rule processors.
 Package rulepack owns the process-level identity contract for composed rule processors.
Package security provides platform-wide security configuration types
 Package security provides platform-wide security configuration types
Package text provides text manipulation utilities.
 Package text provides text manipulation utilities.
Package timestamp provides standardized Unix timestamp handling utilities.
 Package timestamp provides standardized Unix timestamp handling utilities.
Package tlsutil provides TLS configuration utilities for secure connections.
 Package tlsutil provides TLS configuration utilities for secure connections.
Package types provides core type definitions for the semantic event mesh.
 Package types provides core type definitions for the semantic event mesh.
Package worker provides a generic, thread-safe worker pool for concurrent task processing.
 Package worker provides a generic, thread-safe worker pool for concurrent task processing.

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.