go/

Package cache provides a builder for ByteCache implementations with multiple backends.

Package decorators provides cache decorators for cross-cutting concerns.

Package redis provides a Redis-backed cache implementation with singleflight support.

Package connector builds ConnectorSources for the connector family: S3 now, a future GDrive/Salesforce kind added as a new case + sibling package (ARCHITECTURE.md#the-one-idea; the foundation/logger NewFromConfig pattern).

Package decorators wraps a connector ConnectorSource with the shared client observability stack (metrics/tracing/logging).

Package s3 implements the S3 ConnectorSource for the connector family: a "test connection" probe that lists a bounded page under a connector's bucket/prefix using the connector's OWN credentials, over the shared StorageClient (INJECTED — this package never imports go/clients/storage, so there is no lateral same-layer import).

Package database is the database client tier: it selects a SQL connection-pool backend — PostgreSQL today (postgres/) — by Kind and returns the interfaces.DatabasePool contract, so switching database engines is a config change, not a caller edit.

Package postgres is the PostgreSQL backend of the database client tier: a lifecycle-managed *sql.DB pool (Client) plus ORM-independent pool utilities — a boot-time reachability probe (Ping) and a Prometheus pool-stats collector.

Package decorators provides the shared client-boundary resilience stack: one reusable builder that composes, from outermost to innermost,

Package interceptorcore holds the framework-agnostic resilience decisions shared by the gRPC and Connect interceptor stacks.

Package jobs provides a factory for background job queue implementations with multiple backends.

Package decorators composes the Job decorator stack (ARCHITECTURE.md#decorator-order) around a scheduled job function: LeaderElection → RateLimit → Retry → Timeout → Tracing → Metrics → Logging → Job.

Package river provides River-based job queue integration: Runtime (a pgxpool-backed River client that works jobs, with leader-elected periodic jobs), InsertClient (an enqueue-only producer), and Migrate (River's own schema).

Package lock builds a config-selected core/interfaces.Locker — a DistributedLock (keyed, token-fenced, best-effort) plus Hold, the managed acquire-with-watchdog helper a single-active-operation guard depends on.

Package decorators composes cross-cutting concerns — resilience (retry, circuit-breaker, timeout) and observability (logging, metrics, tracing) — around any core/interfaces.DistributedLock, without touching the backend.

Package local provides an in-process DistributedLock backend for single-pod deployments (dev / replica=1), where cross-process coordination is unnecessary.

Package redis provides a cross-pod DistributedLock backend over Redis, for multi-replica deployments (staging/prod).

Package messaging provides a factory for message publisher and subscriber implementations with multiple backends.

Package decorators wraps the messaging MessagePublisher and MessageHandler with cross-cutting concerns.

Package memory provides an in-process messaging backend for no-infra builds and tests.

Package redis provides a Redis Pub/Sub messaging integration (publisher + subscriber) implementing the core MessagePublisher / MessageConsumer contracts over PUBLISH / SUBSCRIBE / PSUBSCRIBE.

Package sqs provides an AWS-SDK-backed SQS messaging integration (publisher + subscriber) usable against real AWS SQS and against ElasticMQ for local dev.

Package replaybuffer selects and builds a ReplayBuffer backend from configuration and wraps it in the resilience + observability decorator stack, mirroring clients/lock.

Package decorators composes cross-cutting concerns — a per-op timeout and the observability trio (logging, metrics, tracing) — around any core/interfaces.ReplayBuffer, without touching the backend.

Package memory provides an in-process ReplayBuffer backend for single-pod deployments (dev / replica=1), where a reconnect lands on the same pod so cross-pod sharing is unnecessary.

Package redis provides a cross-pod ReplayBuffer backend over Redis, for multi-replica deployments (staging/prod) where a reconnect may land on a different pod than the one that buffered the tail.

Package rpc is the RPC client tier: it selects an RPC transport backend — gRPC today (grpc/) — by Kind and returns the RPCClient contract, so switching RPC frameworks is a config change, not a caller edit.

Package grpc provides gRPC server and client factories.

Package interceptors provides gRPC unary interceptors for cross-cutting concerns including observability, resilience, and request lifecycle management.

Package secrets is the credential-source client tier: it selects a secret backend — an environment variable (env/), a git-ignored local file (file/), or AWS Secrets Manager (awssm/) — by Kind and returns the interfaces.Source contract, so switching where a credential is read is a configuration change, not a caller edit.

Package awssm implements the AWS Secrets Manager credential Source: it reads a credential from a Secrets Manager secret (a JSON object) named by a caller-supplied Ref→location mapping, extracting the configured JSON field.

Package env implements the environment-variable credential Source: it resolves a Ref to a configured environment variable name and reads its value via os.Getenv.

Package file implements the file-backed credential Source: it reads and writes credentials in a git-ignored local file (a dotenv-style KEY=value store) named by a caller-supplied Ref→location mapping.

Package storage provides the StorageClient factory.

Package decorators wraps a base StorageClient with the shared client-boundary resilience stack (go/clients/decorators): Bulkhead → Retry → CircuitBreaker → Timeout → Tracing → Metrics → Logging.

Package memory provides an in-memory StorageClient backend for no-infra builds and tests.

Package s3 implements the StorageClient against S3-compatible object stores (AWS S3 and MinIO), selected by configuration.

Package transport is the server-transport client tier: it selects an HTTP/RPC server backend — Connect over net/http today (connect/) — by Kind and returns the interfaces.ServerTransport contract, so switching server frameworks is a config change, not a caller edit.

Package connect provides a Connect/gRPC server factory that mounts proto-generated handlers on a standard net/http.ServeMux.

Package interceptors provides Connect RPC interceptors for cross-cutting concerns.

Package errctx carries a request-scoped sink that captures the original domain error behind a sanitized transport error.

Package errors provides application error types and codes.

Package events is the generic event contract: the Event interface, the metadata every event carries, and a Registry a consumer fills with its own event catalog to parse payloads.

Package interfaces defines the core contracts for the Tech AI Knowledge Engine.

Package principal carries the request's resolved principal — the consumer's own caller type (its authorization model) — in a context.Context.

Package tenant carries the request-scoped tenant (organization) identity in a context.Context.

Package types provides shared domain types used across the platform.

Package engine provides execution infrastructure: concurrent fan-out, observer dispatch, step execution, and context-based observer propagation.

Package gate provides Phase, Gate, GateBuilder, and RunGate for composing AnyJobs into ordered phases with stop-on-failure and error aggregation.

Package job provides the Job[T] type: a discoverer-backed, parallelised, optionally-retried unit of work implementing interfaces.AnyJob.

Package decorators provides logging, metrics, tracing, and recovery wrappers for interfaces.AnyJob.

Package cache provides caching utilities for the foundation layer.

Package decorators provides cache decorators for cross-cutting concerns.

Package config provides a factory for ConfigLoader implementations with multiple backends.

Package infra provides typed configuration structures for Tech AI Knowledge Engine services.

Package listquery is the config surface for the list-query value-suggestion facet: the row threshold above which a facet-eligible field is served from the maintained distinct_values table instead of a live DISTINCT, and the interval at which the reconcile job recomputes refcounts.

Package pipelines is the config surface for the pipeline (orchestration) layer: the per-pipeline operation timeout and the multipart-upload sizing.

Package repos is the config surface for the repository (data-access) layer: the cache TTL/version/key-prefix and the per-operation timeout of the repository decorators.

Package resilience is the tunable config surface for the foundation resilience decorators (retry, breaker, rate-limit, bulkhead, timeout, budget) — the per-environment knobs threaded through the repo/client/interceptor providers Each struct mirrors its primitive's tunable fields with defaults identical to the primitive's DefaultConfig(), so adopting the config surface is behavior-preserving; the providers convert these into the primitive's options.

Package stores is the config surface for the data (stores) layer: the page-size cap, the per-resource default page sizes and the list-query caches, so a deployer can tune pagination without a rebuild.

Package transport is the config surface for the edge (transport) layer: WebSocket, gRPC, CORS and HTTP tuning plus the rate-limiter toggle.

Package workers is the shared config surface for background workers: the common tunables (name, telemetry, relay and sweep cadences, batching) plus the sweep-timing cross-field invariant, so every worker inherits the typed-field + Validate shape.

Package workflows is the config surface for the workflow (orchestration) layer: the per-workflow operation timeout applied through workflow.Builder.WithTimeout.

Package viper provides a Viper-backed ConfigLoader implementation.

Package crypto provides authenticated symmetric encryption for data at rest — e.g.

Package decorate is the type-agnostic operation-decoration mechanism: a common OpMiddleware interface, a Chain composer, and a generic Exec[R] runner that wraps ANY named operation with the cross-cutting decorator stack, regardless of the operation's return type.

Package decorator provides one generic implementation of the cross-cutting decorator stack (timeout, metrics, tracing, logging, recovery) shared by every tier whose unit of work has the shape Execute(ctx, In) (Out, error) — pipelines and workflows today.

Package dtovalidate is the leaf rule library the generated DTO Validate() methods compose Each rule is a small, hand-written check that REUSES the standard library (google/uuid, net/url, path/filepath, net/mail) rather than a hand-rolled regex, and returns a core/errors CodeInvalidInput AppError on violation so the failure classifies to 400 / InvalidArgument at the boundary.

Package fsys provides a real-OS filesystem implementation of the FS interface defined in core/interfaces.

Package git provides reusable git operations for the CLI and tooling layers.

Package lifecycle provides a Manager that starts a set of lifecycle-managed clients in registration order and stops them in reverse for graceful shutdown, so a composition root wires its clients once and coordinates their startup and teardown centrally instead of by hand.

Package listquery is the pure, ORM-free half of the list-query SDK a per-resource filter allow-list (Map) + sort allow-list (Set), a JSON filter-DSL parser that compiles a client filter string into the core/types Filter contract (gated by the allow-list so only allow-listed fields with type-checked values reach a query), and the shared Compile/CompileOrder fold that walks that IR through a core/interfaces.QueryBackend algebra.

Package logger provides structured logging with multiple backend implementations.

Package logctx provides shared context utilities for logger sub-packages.

Package stdlib provides a pure stdlib slog logger implementation.

Package zap provides a zap-backed logger implementation with PII redaction.

Package metrics provides a builder for the Prometheus metrics implementation.

Package noop provides a no-op metrics implementation that silently discards all metric operations.

Package prom provides a Prometheus-backed metrics implementation.

Package middleware provides stdlib net/http middleware for composing request processing pipelines without external web frameworks.

Package options provides a generic functional options pattern for configuring types.

Package resilience provides fault-tolerance primitives as standalone subpackages.

Package adaptivethrottle provides a client-side adaptive throttler (Google SRE "Handling Overload"): it sheds a growing fraction of outbound requests locally when a backend's accept-rate drops, protecting the backend from a client-side retry storm.

Package budget tracks retry consumption across a call chain via context propagation.

Package bulkhead provides a builder for Bulkhead implementations with multiple backends.

Package adaptive provides a self-tuning (AIMD) concurrency-limiting Bulkhead.

Package channel provides a channel-based semaphore bulkhead implementation.

Package circuitbreaker provides a builder for CircuitBreaker implementations with multiple backends.

Package gobreaker provides a circuit breaker backed by sony/gobreaker/v2.

Package deadletter provides the dead-letter-queue facade — the Go mirror of techai_webutils.foundation.resilience.dlq.

Package dedup provides message deduplication for exactly-once processing under at-least-once delivery.

Package hedge provides a builder for Hedger implementations that reduce tail latency by racing a backup attempt.

Package leader provides leader election for single-instance job execution.

Package ratelimiter provides a builder for RateLimiter implementations with multiple backends.

Package token provides a token-bucket rate limiter backed by golang.org/x/time/rate.

Package reswire builds resilience primitives (retrier, circuit breaker) from a ConfigLoader + the schema/resilience config surface.

Package retry provides a builder for Retrier implementations with multiple backends.

Package exponential provides an exponential backoff retrier using cenkalti/backoff/v5.

Package system provides CommandRunner implementations for executing external commands.

Package tracer provides distributed tracing with swappable backends.

Package nooptracer provides a no-op tracer that satisfies interfaces.Tracer.

Package oteltracer provides an OpenTelemetry-backed tracer implementation.

Package validator provides a small, generic business-rule validator for the service layer — the below-transport-boundary complement to the proto/request validation performed at the transport edge (connect ValidateInterceptor).

Package pipeline provides the base pipeline implementation.

Package decorators provides fluent decorator composition for pipelines.

Package gorm is the GORM ORM adapter (repos/adapters/gorm): a lifecycle-managed opener for a *gorm.DB selected by Kind (lazily, in Start), so a consumer can put its repositories on GORM, or switch another persistence adapter it owns for this one, as a composition-root wiring change rather than a rewrite.

Package errors provides database error mapping to domain errors.

Package postgres provides PostgreSQL-specific DB error mapping.

Package repository provides the BaseRepository implementation with decorator support and keyset pagination for building data access layers.

Package compiler selects the query-compiler backend for a configured Kind.

Package ent is the Ent/SQL backend of the multi-target query-compilation SDK: it interprets the list-query IR into Ent dialect/sql predicates and order options — the func(*sql.Selector) shape every Ent query accepts via query.Where(predicate.T(pred)) and query.Order(opt).

Package decorators provides fluent decorator composition for repositories.

Package entlist is the Ent glue shared by every app's ListRunner adapters: it folds a resolved-column ListSpec's predicates and ORDER BY into Ent query-node functions through the entcompiler QueryBackend.

Package service provides BaseService with decorator support for building domain service layers with cross-cutting concerns.

Package decorators provides fluent decorator composition for services.

Package fixtures provides thin, hand-written factories over the GENERATED gomock mocks in the sibling mocks package.

Package elasticmq provides a testcontainers-based ElasticMQ (SQS-compatible) instance for integration tests.

Package minio provides a testcontainers-based MinIO instance for integration tests.

Package postgres provides a generic testcontainers-based PostgreSQL database for integration tests.

Package redis provides a testcontainers-based Redis instance for integration tests.

Package e2ekit is the gen-free shared test-kit for endpoint E2E + telemetry suites.

Package store (testutil) provides a interfaces.Store implementation that supports call counting and error injection for use in tests.

Package suite provides test suite constructors for unit and integration tests.

Package base provides the base test suite with shared utilities.

Package integration holds the Go integration tests: each file exercises a clients-tier backend against the real service it wraps, started in a throwaway testcontainers container by the fixtures under go/tests/fixtures/dbtest — Redis (cache, lock, messaging, replay buffer), MinIO (S3 storage and the S3 connector), ElasticMQ (SQS messaging), and PostgreSQL (River's runtime and migrations).

Package mocks is a generated GoMock package.

Package decorators provides fluent decorator composition for transport handlers.

Package docs provides reusable HTTP handlers for serving OpenAPI specs and Redoc UI documentation pages.

Package jsonapi provides HTTP middleware that transforms Vanguard REST responses into [JSON:API](https://jsonapi.org/format/) envelope format.

Package rest provides HTTP response helpers for REST API handlers.

Package rpc provides Connect RPC utilities for bidirectional mapping between domain AppErrors and Connect/gRPC status codes.

Package workflow provides the base workflow implementation.

Package decorators provides fluent decorator composition for workflows.