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)

launcher/banner.go

@@ -0,0 +1,51 @@
+package launcher
+
+import (
+	"fmt"
+	"os"
+	"runtime/debug"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/contracts/observability"
+)
+
+func printBanner(identifiables []observability.Identifiable) {
+	v := strings.ToLower(os.Getenv("EINHERJAR_BANNER"))
+	if v == "off" || v == "false" {
+		return
+	}
+	fmt.Fprintf(os.Stdout, bannerText, coreVersion())
+	for _, id := range identifiables {
+		path := strings.TrimPrefix(id.ModulePath(), "code.nochebuena.dev/")
+		fmt.Fprintf(os.Stdout, "  · %-25s %s\n", path, id.ModuleVersion())
+	}
+	if len(identifiables) > 0 {
+		fmt.Fprintln(os.Stdout)
+	}
+}
+
+func coreVersion() string {
+	const path = "code.nochebuena.dev/einherjar/core"
+	if info, ok := debug.ReadBuildInfo(); ok {
+		for _, dep := range info.Deps {
+			if dep.Path == path {
+				return dep.Version
+			}
+		}
+		if info.Main.Path == path {
+			return info.Main.Version
+		}
+	}
+	return "(devel)"
+}
+
+const bannerText = `
+  ███████╗██╗███╗   ██╗██╗  ██╗███████╗██████╗      ██╗ █████╗ ██████╗
+  ██╔════╝██║████╗  ██║██║  ██║██╔════╝██╔══██╗     ██║██╔══██╗██╔══██╗
+  █████╗  ██║██╔██╗ ██║███████║█████╗  ██████╔╝     ██║███████║██████╔╝
+  ██╔══╝  ██║██║╚██╗██║██╔══██║██╔══╝  ██╔══██╗██   ██║██╔══██║██╔══██╗
+  ███████╗██║██║ ╚████║██║  ██║███████╗██║  ██║╚█████╔╝██║  ██║██║  ██║
+  ╚══════╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ╚════╝ ╚═╝  ╚═╝╚═╝  ╚═╝
+  code.nochebuena.dev/einherjar  ·  Chosen warriors. Not for themselves.  ·  %s
+
+`

launcher/config.go

@@ -0,0 +1,13 @@
+package launcher
+
+import "time"
+
+// Config configures a Launcher instance.
+// The zero value is valid: 15-second component stop timeout.
+type Config struct {
+	// ComponentStopTimeout is the maximum time allowed for each component's OnStop.
+	// Default: 15 seconds.
+	ComponentStopTimeout time.Duration `env:"EINHERJAR_COMPONENT_STOP_TIMEOUT" envDefault:"15s"`
+}
+
+const defaultComponentStopTimeout = 15 * time.Second

launcher/doc.go

@@ -0,0 +1,27 @@
+// Package launcher orchestrates the application lifecycle.
+//
+// A Launcher manages infrastructure components through three ordered phases:
+//
+//  1. OnInit — all components initialize in registration order
+//  2. BeforeStart hooks — dependency injection wiring runs
+//  3. OnStart — all components start in registration order
+//
+// On shutdown (OS signal or programmatic Shutdown call), OnStop is called for
+// every component in reverse registration order, ensuring dependents stop
+// before their dependencies.
+//
+// Usage:
+//
+//	logger := logz.New(logz.Options{JSON: true})
+//	lc := launcher.New(logger)
+//
+//	lc.Append(db, cache, server)
+//	lc.BeforeStart(func() error {
+//	    return server.RegisterRoutes(db, cache)
+//	})
+//
+//	if err := lc.Run(); err != nil {
+//	    logger.Error("launcher failed", err)
+//	    os.Exit(1)
+//	}
+package launcher

launcher/hook.go

@@ -0,0 +1,6 @@
+package launcher
+
+// Hook is a function executed during the assembly phase — after all OnInit calls
+// and before all OnStart calls. Use hooks for dependency injection wiring that
+// requires every component to be initialized before connections are established.
+type Hook func() error

launcher/launcher.go

@@ -0,0 +1,162 @@
+package launcher
+
+import (
+	"context"
+	"os"
+	"os/signal"
+	"sync"
+	"syscall"
+	"time"
+
+	"code.nochebuena.dev/einherjar/contracts/lifecycle"
+	"code.nochebuena.dev/einherjar/contracts/logging"
+	"code.nochebuena.dev/einherjar/contracts/observability"
+)
+
+// Launcher manages the application lifecycle: init → assemble → start → wait → shutdown.
+type Launcher interface {
+	// Append adds one or more components. Registered in the order they are appended;
+	// shutdown runs in reverse order.
+	Append(components ...lifecycle.Component)
+	// BeforeStart registers hooks that run after all OnInit calls and before all OnStart
+	// calls. Use for dependency injection wiring.
+	BeforeStart(hooks ...Hook)
+	// Run executes the full application lifecycle. Blocks until an OS shutdown signal is
+	// received or Shutdown is called. Returns an error if any lifecycle step fails.
+	// The caller is responsible for calling os.Exit(1) when needed.
+	Run() error
+	// Shutdown triggers a graceful shutdown and waits for Run to return.
+	// ctx controls the caller-side wait timeout — it does NOT override
+	// Config.ComponentStopTimeout for individual components.
+	// Safe to call multiple times (idempotent).
+	Shutdown(ctx context.Context) error
+}
+
+var _ Launcher = (*launcher)(nil)
+
+// New returns a Launcher configured by opts. The zero value of Config is valid.
+func New(logger logging.Logger, opts ...Config) Launcher {
+	o := Config{ComponentStopTimeout: defaultComponentStopTimeout}
+	if len(opts) > 0 {
+		if opts[0].ComponentStopTimeout > 0 {
+			o.ComponentStopTimeout = opts[0].ComponentStopTimeout
+		}
+	}
+	return &launcher{
+		logger:     logger,
+		opts:       o,
+		components: make([]lifecycle.Component, 0),
+		shutdownCh: make(chan struct{}),
+		doneCh:     make(chan struct{}),
+	}
+}
+
+type launcher struct {
+	logger       logging.Logger
+	opts         Config
+	components   []lifecycle.Component
+	beforeStart  []Hook
+	shutdownCh   chan struct{}
+	doneCh       chan struct{}
+	shutdownOnce sync.Once
+}
+
+func (l *launcher) Append(components ...lifecycle.Component) {
+	l.components = append(l.components, components...)
+}
+
+func (l *launcher) BeforeStart(hooks ...Hook) {
+	l.beforeStart = append(l.beforeStart, hooks...)
+}
+
+// Run executes the full application lifecycle:
+//  1. Prints the startup banner (unless EINHERJAR_BANNER=off).
+//  2. OnInit for all components (in registration order).
+//  3. BeforeStart hooks (in registration order).
+//  4. OnStart for all components (in registration order).
+//  5. Blocks until an OS signal or Shutdown() is called.
+//  6. stopAll — OnStop for all components (in reverse order).
+func (l *launcher) Run() error {
+	var ids []observability.Identifiable
+	for _, c := range l.components {
+		if id, ok := c.(observability.Identifiable); ok {
+			ids = append(ids, id)
+		}
+	}
+	printBanner(ids)
+	defer close(l.doneCh)
+
+	l.logger.Info("launcher: starting init phase (OnInit)")
+	for _, c := range l.components {
+		if err := c.OnInit(); err != nil {
+			return err
+		}
+	}
+
+	l.logger.Info("launcher: running assembly hooks (BeforeStart)")
+	for _, hook := range l.beforeStart {
+		if err := hook(); err != nil {
+			return err
+		}
+	}
+
+	l.logger.Info("launcher: starting components (OnStart)")
+	for _, c := range l.components {
+		if err := c.OnStart(); err != nil {
+			l.logger.Error("launcher: OnStart failed, triggering shutdown", err)
+			l.stopAll()
+			return err
+		}
+	}
+
+	l.logger.Info("launcher: application ready")
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
+	defer signal.Stop(quit)
+
+	select {
+	case s := <-quit:
+		l.logger.Info("launcher: termination signal received", "signal", s.String())
+	case <-l.shutdownCh:
+		l.logger.Info("launcher: programmatic shutdown requested")
+	}
+
+	l.stopAll()
+	return nil
+}
+
+func (l *launcher) Shutdown(ctx context.Context) error {
+	l.shutdownOnce.Do(func() {
+		close(l.shutdownCh)
+	})
+
+	select {
+	case <-l.doneCh:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func (l *launcher) stopAll() {
+	l.logger.Info("launcher: stopping all components")
+
+	for i := len(l.components) - 1; i >= 0; i-- {
+		done := make(chan struct{})
+		go func(c lifecycle.Component) {
+			if err := c.OnStop(); err != nil {
+				l.logger.Error("launcher: error during OnStop", err)
+			}
+			close(done)
+		}(l.components[i])
+
+		select {
+		case <-done:
+		case <-time.After(l.opts.ComponentStopTimeout):
+			l.logger.Error("launcher: component OnStop timed out", nil)
+		}
+	}
+
+	l.logger.Info("launcher: all components stopped")
+}