feat(contracts): initial implementation (v1.0.0)

Introduces code.nochebuena.dev/einherjar/contracts — the zero-dependency
foundation of the Einherjar framework. Defines the interfaces and minimal
types consumed by every starter. Zero external dependencies. Zero Einherjar
dependencies. Nothing is above it in the dependency graph.

lifecycle:
- Component — OnInit, OnStart, OnStop three-phase lifecycle hooks

observability:
- Level (LevelCritical=0, LevelDegraded); zero value is the safe default
- Checkable — HealthCheck, Name, Priority
- Identifiable — ModulePath, ModuleVersion; implemented by all starters to
  surface module identity and version in the startup banner

logging:
- Logger — Debug, Info, Warn, Error, With, WithContext

errs:
- CodedError — ErrorCode() string; satisfied by core/xerrors.Err
- ContextualError — ErrorContext() map[string]any; satisfied by core/xerrors.Err

security:
- Identity value type — UID, TenantID, DisplayName, Email; NewIdentity, WithTenant
- Permission (int64), MaxPermission=62, PermissionMask — Has, Grant
- PermissionProvider — ResolveMask(ctx, uid, resource) (PermissionMask, error)
- SecurityBag value type — immutable request-scoped security context; carries
  Identity and arbitrary typed attributes (hardware IDs, grant codes, etc.);
  With copies the attribute map on every call to preserve receiver-invariant behaviour
- NewSecurityBag, Identity, WithIdentity, Get, With
- SetBagInContext / BagFromContext — full bag context storage
- SetInContext / FromContext — backed by SecurityBag; all four cross-function
  combinations (SetInContext+BagFromContext, SetBagInContext+FromContext) are valid

One file per type; CT-6 enforced by compliance test AST walk.
This commit is contained in:
2026-05-29 15:43:08 +00:00
commit 098a2098f8
31 changed files with 2230 additions and 0 deletions

18
lifecycle/component.go Normal file
View File

@@ -0,0 +1,18 @@
package lifecycle
// Component is the lifecycle interface implemented by all managed infrastructure
// components. The framework calls OnInit on every registered component, then runs
// BeforeStart hooks, then calls OnStart. OnStop is called in reverse registration
// order during graceful shutdown. Returning a non-nil error from any hook aborts
// the phase and triggers shutdown.
type Component interface {
// OnInit initializes the component: open connections, allocate resources.
// Called sequentially for all components before any OnStart is invoked.
OnInit() error
// OnStart starts background services — goroutines, listeners, background loops.
// Called after all OnInit calls succeed and all BeforeStart hooks have run.
OnStart() error
// OnStop stops the component and releases all resources.
// Called in reverse registration order during graceful shutdown.
OnStop() error
}