feat(core): initial implementation — launcher, logz, xerrors, valid

Introduces `code.nochebuena.dev/einherjar/core` — the foundational implementation
module of the Einherjar framework. Provides four sub-packages that together cover
every service's baseline needs: lifecycle management, structured logging, typed
errors, and struct validation.

- launcher: Launcher interface — three-phase managed lifecycle (OnInit → BeforeStart
  hooks → OnStart → OS signal wait → OnStop in reverse). Accepts
  lifecycle.Component and logging.Logger from contracts. Prints an ASCII art banner
  at startup (EINHERJAR_BANNER=off to suppress). Banner includes core version via
  runtime/debug.ReadBuildInfo() and a loaded-module list for every registered
  component that implements observability.Identifiable. Config struct with
  EINHERJAR_COMPONENT_STOP_TIMEOUT env tag (caarlos0/env syntax, default 15s).

- logz: Logger implementation backed by log/slog. Returns contracts/logging.Logger.
  Detects errs.CodedError and errs.ContextualError (from contracts/errs) to enrich
  log records automatically — replaces the private duck-typed bridge from micro-lib.
  Context helpers: WithRequestID, WithField, WithFields, GetRequestID. Config struct
  with EINHERJAR_LOG_LEVEL (default INFO) and EINHERJAR_LOG_JSON (default false) env
  tags (caarlos0/env syntax); programmatic-only fields StaticArgs and Writer carry no
  tags.

- xerrors: Typed error codes with context enrichment. Complete gRPC canonical set
  (16 codes) plus HTTP 410 ErrGone. Adds ErrOutOfRange, ErrAborted, ErrDataLoss
  over micro-lib. One convenience constructor per code. *Err declares compile-time
  satisfaction of errs.CodedError and errs.ContextualError.

- valid: Struct validation wrapping go-playground/validator/v10. Validator interface
  + MessageProvider interface with full built-in tag coverage (~150 tags) in both
  DefaultMessages (English) and SpanishMessages (Spanish). Backend fully hidden;
  returns *xerrors.Err with ErrInvalidInput or ErrInternal. FieldLevel interface
  abstracts the backend's field-level access for custom validators.
  WithCustomValidator registers custom validation tags at construction time;
  OverrideProvider chains a tag→handler map with a fallback MessageProvider for
  custom tag messages without re-implementing built-ins.

Compliance test enforces CT-6 (at most one exported TypeSpec per file via AST) and
verifies behavioural correctness of all four sub-packages, including custom validator
registration and OverrideProvider composition. Compile-time var _ assertions prove
interface satisfaction.

docs: ADR-001 (core module composition), ADR-002 (logz contracts/errs adoption),
ADR-003 (Config naming convention and caarlos0/env tag standard)

logz/config.go

@@ -0,0 +1,20 @@
+package logz
+
+import (
+	"io"
+	"log/slog"
+)
+
+// Config configures a Logger instance.
+// The zero value is valid: INFO level, text output, os.Stdout, no static args.
+type Config struct {
+	// Level is the minimum log level. Default: slog.LevelInfo (zero value).
+	Level slog.Level `env:"EINHERJAR_LOG_LEVEL" envDefault:"INFO"`
+	// JSON enables JSON output. Default: false (text output).
+	JSON bool `env:"EINHERJAR_LOG_JSON" envDefault:"false"`
+	// StaticArgs are key-value pairs attached to every log record.
+	StaticArgs []any
+	// Writer is the output destination. Defaults to os.Stdout when nil.
+	// Accepts any io.Writer: *os.File, bytes.Buffer, io.MultiWriter, etc.
+	Writer io.Writer
+}

logz/context.go

@@ -0,0 +1,40 @@
+package logz
+
+import "context"
+
+type ctxRequestIDKey struct{}
+type ctxExtraFieldsKey struct{}
+
+// WithRequestID adds a request correlation ID to the context.
+func WithRequestID(ctx context.Context, id string) context.Context {
+	return context.WithValue(ctx, ctxRequestIDKey{}, id)
+}
+
+// GetRequestID retrieves the correlation ID from the context.
+// Returns "" if not present or if ctx is nil.
+func GetRequestID(ctx context.Context) string {
+	if ctx == nil {
+		return ""
+	}
+	id, _ := ctx.Value(ctxRequestIDKey{}).(string)
+	return id
+}
+
+// WithField adds a single key-value pair to the context for logging.
+func WithField(ctx context.Context, key string, value any) context.Context {
+	return WithFields(ctx, map[string]any{key: value})
+}
+
+// WithFields adds multiple key-value pairs to the context for logging.
+// Merges with any existing fields — does not overwrite the whole map.
+func WithFields(ctx context.Context, fields map[string]any) context.Context {
+	existing, _ := ctx.Value(ctxExtraFieldsKey{}).(map[string]any)
+	newMap := make(map[string]any, len(existing)+len(fields))
+	for k, v := range existing {
+		newMap[k] = v
+	}
+	for k, v := range fields {
+		newMap[k] = v
+	}
+	return context.WithValue(ctx, ctxExtraFieldsKey{}, newMap)
+}

logz/doc.go

@@ -0,0 +1,27 @@
+// Package logz provides a structured, leveled logger backed by the standard
+// library's log/slog package.
+//
+// logz.New returns a logging.Logger (from contracts). No concrete type is
+// exported — callers depend on the interface, not the implementation.
+//
+// Error enrichment: when an error passed to Logger.Error implements
+// errs.CodedError or errs.ContextualError (from contracts/errs), the
+// corresponding fields are automatically appended to the log record without
+// either package importing the other.
+//
+// Context enrichment: WithRequestID, WithField, and WithFields store values
+// in context.Context. Logger.WithContext reads them back and attaches
+// request_id and any extra fields to every subsequent log record.
+//
+// Usage:
+//
+//	logger := logz.New(logz.Options{
+//	    Level:      slog.LevelDebug,
+//	    JSON:       true,
+//	    StaticArgs: []any{"service", "api"},
+//	})
+//
+//	ctx = logz.WithRequestID(ctx, requestID)
+//	reqLogger := logger.WithContext(ctx)
+//	reqLogger.Info("handling request", "path", r.URL.Path)
+package logz

logz/logger.go

@@ -0,0 +1,103 @@
+package logz
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"os"
+
+	"code.nochebuena.dev/einherjar/contracts/errs"
+	"code.nochebuena.dev/einherjar/contracts/logging"
+)
+
+var _ logging.Logger = (*slogLogger)(nil)
+
+// New returns a Logger configured by cfg.
+func New(cfg Config) logging.Logger {
+	w := cfg.Writer
+	if w == nil {
+		w = os.Stdout
+	}
+
+	handlerOpts := &slog.HandlerOptions{Level: cfg.Level}
+	var handler slog.Handler
+	if cfg.JSON {
+		handler = slog.NewJSONHandler(w, handlerOpts)
+	} else {
+		handler = slog.NewTextHandler(w, handlerOpts)
+	}
+
+	base := slog.New(handler)
+	if len(cfg.StaticArgs) > 0 {
+		base = base.With(cfg.StaticArgs...)
+	}
+
+	return &slogLogger{logger: base}
+}
+
+type slogLogger struct {
+	logger *slog.Logger
+}
+
+func (l *slogLogger) Debug(msg string, args ...any) { l.logger.Debug(msg, args...) }
+func (l *slogLogger) Info(msg string, args ...any)  { l.logger.Info(msg, args...) }
+func (l *slogLogger) Warn(msg string, args ...any)  { l.logger.Warn(msg, args...) }
+
+func (l *slogLogger) Error(msg string, err error, args ...any) {
+	args = enrichErrorAttrs(err, args)
+	if err != nil {
+		args = append(args, slog.Any("error", err))
+	}
+	l.logger.Error(msg, args...)
+}
+
+func (l *slogLogger) With(args ...any) logging.Logger {
+	return &slogLogger{logger: l.logger.With(args...)}
+}
+
+func (l *slogLogger) WithContext(ctx context.Context) logging.Logger {
+	if ctx == nil {
+		return l
+	}
+
+	newLogger := l.logger
+	modified := false
+
+	if id, ok := ctx.Value(ctxRequestIDKey{}).(string); ok && id != "" {
+		newLogger = newLogger.With(slog.String("request_id", id))
+		modified = true
+	}
+
+	if fields, ok := ctx.Value(ctxExtraFieldsKey{}).(map[string]any); ok {
+		for k, v := range fields {
+			newLogger = newLogger.With(k, v)
+		}
+		modified = true
+	}
+
+	if !modified {
+		return l
+	}
+
+	return &slogLogger{logger: newLogger}
+}
+
+// enrichErrorAttrs appends error_code and context fields from err when err
+// satisfies errs.CodedError or errs.ContextualError from contracts.
+// Returns attrs unchanged if err is nil or satisfies neither interface.
+func enrichErrorAttrs(err error, attrs []any) []any {
+	if err == nil {
+		return attrs
+	}
+	var ec errs.CodedError
+	if errors.As(err, &ec) {
+		attrs = append(attrs, "error_code", ec.ErrorCode())
+	}
+	var ectx errs.ContextualError
+	if errors.As(err, &ectx) {
+		for k, v := range ectx.ErrorContext() {
+			attrs = append(attrs, k, v)
+		}
+	}
+	return attrs
+}