kernel

type Deps struct {
	Pool *pgxpool.Pool
	// Platform is the app_platform pool for cross-tenant kernel work (outbox relay,
	// job runner, seed sync) and, in the api, cross-tenant API-key verification. Both
	// the generated api and worker mains build it BEFORE Boot and wire it here, and
	// app.Boot's RLS-enforcement check (M3) validates it when non-nil. It is nil only
	// for the migrate process, which serves no tenant traffic and opts out of that
	// check via app.SkipRLSEnforcementCheck. A custom api/worker main MUST wire it
	// too — leaving it nil silently skips the M3 backstop for the platform pool.
	Platform *pgxpool.Pool
	Tx       database.TxManager
	Audit    authz.AuditSink // optional; nil → a logging sink
	// Storage is the object-storage adapter backing the document framework.
	// Optional: when nil, Kernel.Documents is nil and modules that require it fail
	// boot only if they actually register a document class (checked by app.Boot).
	Storage storage.Adapter
	// Secrets resolves secret references (webhook signing secrets, integration
	// credentials). Optional; when nil, resolving a ref errors at use time.
	Secrets secrets.Provider
	// WebhookSender delivers outbound webhooks. Optional; nil → the real HTTP sender.
	WebhookSender webhook.Sender
	// Metrics is the observability sink (Prometheus adapter in production).
	// Optional; nil → observability.NoOp so call sites never nil-check.
	Metrics observability.Metrics
	// Tracer is the distributed-tracing port (OTel adapter in production).
	// Optional; nil → observability.NoOpTracer. Wired into the outbox writer so
	// emitted events carry the request's trace context across the async boundary
	// (roadmap O1/CA-9).
	Tracer observability.Tracer
	// AuthzCacheTTL, when > 0, wraps the authorization store in a per-actor
	// ActiveAssignments cache with this TTL (roadmap R1/CA-2). DEFAULT OFF
	// (zero) — enabling it accepts up-to-TTL stale-allow after a revocation on
	// another pod, so keep the TTL short and call Kernel.AuthzCache.Invalidate
	// from your role grant/revoke paths for immediate effect on this pod.
	AuthzCacheTTL time.Duration
}

type Kernel struct {
	Cfg             config.Framework
	Log             *slog.Logger
	Pool            *pgxpool.Pool
	Platform        *pgxpool.Pool // app_platform pool for cross-tenant kernel work; see Deps.Platform for the wiring contract (nil only for migrate)
	Tx              database.TxManager
	Authz           authz.Evaluator
	Perms           *authz.Registry
	Resources       *resource.Registry
	Rules           *rules.Registry
	RulesResolver   *rules.Resolver
	Workflows       *workflow.Registry
	WorkflowRuntime *workflow.Runtime

	// Data lifecycle (roadmap E2). RetentionClasses is the shared record-class
	// registry modules register their dispose/export/erase callbacks into during
	// boot; Retention is the engine that drives scheduled disposition and DSR
	// fulfilment over them.
	RetentionClasses *retention.Registry
	Retention        *retention.Engine

	// Document / file framework (Phase 8). DocumentClasses + DocumentHooks are the
	// shared registration pointers modules write into during Register; Documents is
	// nil when no storage adapter is provided (an api-only process may run without
	// object storage). Comments/Attachments need no storage.
	DocumentClasses *document.Registry
	DocumentHooks   *document.Hooks
	Documents       *document.Service
	Comments        *comment.Service
	Attachments     *attachment.Service

	// Notification / webhook / integration framework (Phase 9). NotifyTemplates
	// and IntegrationProviders are the shared registration pointers modules write
	// into during Register; Notify/Webhooks/Integrations are the runtime services.
	NotifyTemplates      *notify.Registry
	Notify               *notify.Service
	Webhooks             *webhook.Service
	IntegrationProviders *integration.Registry
	Integrations         *integration.Store

	// Metrics is the observability sink shared by kernel components (RED
	// middleware, scheduler lag, DLQ depth, webhook breaker, rate-limit drops).
	// Never nil — defaults to observability.NoOp when no adapter is wired.
	Metrics observability.Metrics

	// Tracer is the distributed-tracing port; never nil (NoOpTracer default). The
	// outbox writer captures its trace context; the relay continues it (CA-9).
	Tracer observability.Tracer

	// AuthzCache is the per-actor assignment cache wrapping the evaluator's store
	// when Deps.AuthzCacheTTL > 0; nil when caching is disabled. It caches
	// ActiveAssignments (which pre-join role_permissions), so BOTH an actor's
	// role grants/revokes AND a role's permission set can otherwise be served
	// stale up to the TTL. To keep it fresh (CA-2):
	//   - actor_assignment grant/revoke (product-owned write): call
	//     AuthzCache.Invalidate(tenant, capacity) — or InvalidateTenant for a
	//     bulk change — right after the write commits.
	//   - seed / authorization-spine sync (roles + role_permissions): pass this
	//     handle to seeds.Sync, which calls InvalidateAll after the writes commit.
	// ABAC policies and ReBAC relationship edges are NOT cached (they pass
	// through / are checked directly each Evaluate), so a policy activation or a
	// granted_via edge change is never stale and needs no invalidation.
	AuthzCache *authz.CachingStore

	// Evidence-layer services exposed to modules via module.Context (roadmap CA-11):
	// Audit (field-level audit + hash chain), Sequence (gap-free numbering), Bulk
	// (chunked resumable ops), Artifacts (immutable versioned artifacts).
	Audit     *kaudit.Writer
	Sequence  *sequence.Allocator
	Bulk      *bulk.Service
	Artifacts *artifact.Pipeline
	// contains filtered or unexported fields
}