framework

Package assembly provides the CoreAssembly that orchestrates Cell lifecycle (register, start, stop, health).

Package auth holds the kernel-level authentication plan model: the sealed AuthPlan / ListenerAuth interfaces, their five typed implementations (None, JWT, JWTFromAssembly, MTLS, ServiceToken), and the narrow dependency interfaces (IntentTokenVerifier, NonceStore, ServiceKeyring, AuthProvider, ...) that runtime/auth concrete types satisfy structurally.

Package authtest provides composition-root convenience helpers for AuthPlan constructors.

Package cell defines the core Cell and Slice abstractions for the GoCell framework: interfaces (CellIdentity / CellLifecycle / CellStatus / CellInventory composed into Cell), the BaseCell implementation, and the Registrar surface a Cell uses to declare routes / subscriptions / health probes / lifecycle hooks / config-reload callbacks.

Package celltest provides test utilities for kernel/cell types.

Package cellvocab is the single source of truth for the GoCell metadata vocabulary — the typed enums (CellType, ContractKind, ContractRole, CellLifecycle, ContractLifecycle, Level), their parsers/predicates, and the canonical consistency level ordering.

Package circuitbreaker provides an in-process three-state circuit breaker (closed/half-open/open) as a clock-only kernel primitive: it has no infrastructure dependency, only kernel/clock for time.

Package clock is GoCell's platform-level Clock abstraction.

Package clockmock provides a deterministic clock.Clock implementation driven by explicit FakeClock.Advance and FakeClock.Set calls.

Package command provides L4 (DeviceLatent) command queue primitives for unicast device commands with durable ack semantics.

Package commandtest provides shared conformance assertions for command.Queue + command.ActiveScanner implementations.

Package contractspec defines the runtime descriptor type for one contract endpoint, shared by the layers that bind contracts to wire protocols.

Package crypto defines the kernel-level cryptographic interfaces: KeyProvider, KeyHandle, ValueTransformer, and CurrentKeyIDProvider.

Package ctxkeys provides typed context keys for Cell-model identifiers (cell, slice, journey, contract) propagated through context.Context.

Package depgraph defines the core data model for the GoCell package-level dependency graph: Graph, Node, Stats, and the layer/cell/slice classifiers.

Package fsm provides generic helpers for map-based finite-state-machine transition tables used by kernel state machines.

Package governance implements validation rules for GoCell metadata.

Package healthz defines the kernel-level interface for readiness probes.

Package idempotency defines the consumer-side idempotency interface (Claimer with two-phase Claim / Commit / Release semantics) used by kernel/outbox.ConsumerBase to deduplicate event delivery.

Package journey provides query access to Journey metadata and status.

Package lifecycle provides the ContextCloser interface and adapters for managing resource teardown with context-aware shutdown budgets.

Package metadata implements structural derivation for AssemblyMeta and related types.

Package metadatatest provides typed builders for constructing kernel/metadata fixtures in *_test.go files.

Package metautil holds shared metadata limits and validation primitives used by kernel-level transports (kernel/outbox, kernel/command).

Package observability is the namespace root for GoCell's provider-neutral metrics and pool-stats abstractions.

Package correlation provides a sealed read-model carrying the three cross-cutting observability IDs (trace, request, correlation) for use in issue #1048 (trace → audit reverse lookup).

Package metrics defines a provider-neutral metrics abstraction used by kernel modules that emit counters and histograms without importing any specific backend (Prometheus, OTel, …).

Package metricstest provides the cross-implementation conformance harness for the kernel metrics no-skip-on-cancel contract.

Package poolstats defines a provider-neutral connection-pool snapshot interface.

Package outbox defines interfaces for the transactional outbox pattern: Writer (insert within a transaction), Emitter (write-or-direct abstraction), Relay (poll-and-publish), Publisher (fire-and-forget), and Subscriber (consume).

Package outboxtest provides a reusable conformance test suite for outbox.Publisher and outbox.Subscriber implementations.

Package persistence defines shared persistence abstractions for the GoCell framework.

Package persistencetest provides conformance suites for persistence.TxRunner implementations.

Package projection declares the kernel-level contracts for the CQRS projection lifecycle harness: the business event→state Apply hook, the CheckpointStore offset abstraction, the MemCursor / MemReplaySource demo helpers, the functional Option seam, and the rebuild-lifecycle Phase enum.

Package projectiontest provides conformance test helpers for projection.CheckpointStore, projection.ReplaySource, and projection.Cursor implementations.

Package reconcile is GoCell's L4 desired-state convergence harness, a level-triggered control loop modeled on Kubernetes controller-runtime's Reconciler.

Package reconciletest provides public test-support fakes and conformance suites for kernel/reconcile consumers and LeaderElector adapters.

Package registry provides indexed, read-only access to parsed GoCell project metadata (cells, slices, contracts).

Package saga provides the L3 (WorkflowEventual) saga orchestration state machine: the Status lifecycle, the Instance record, and the pure transition functions (AdvanceSaga, AdvanceStep, Transition) that advance an instance.

Package journal provides the durable, append-only Journal for L3 (WorkflowEventual) saga orchestration: the interface the runtime Coordinator (PR-03) and the PostgreSQL store (PR-04) build on, plus an in-memory implementation (MemJournal) for tests and development.

Package sagajournaltest provides a reusable conformance suite for implementations of journal.Journal.

Package sagaprojection bridges kernel/saga/journal.GlobalReader to the projection harness (projection.ReplaySource + projection.Cursor + cellvocab.ProjectionEvent).

Package sagaregtest provides a reusable conformance suite for implementations of saga.Resolver.

Package verify provides verify-command introspection used by `gocell verify` and by kernel/governance VERIFY-* rules.

Package webhook is the kernel-level pure-computation core for GoCell's bidirectional webhook capability (KERNEL-WEBHOOK-01): inbound receiver verification and outbound dispatcher signing.

Package webhooktest provides a sign↔verify conformance suite for webhook.Signer and webhook.Verifier implementations.

Package worker defines the Worker domain contract.

Package wrapper binds contracts to runtime observability primitives.

Package aeadutil provides pure AES-GCM helpers shared across runtime/crypto and adapters/vault.

Package authz is the framework-level **authorization decision vocabulary** (the PDP contract) returned by auth.Authorizer.

Package cmdrun centralizes whitelisted subprocess invocation for governance and verify helpers (gocell validate / gocell check / golangci-lint runner / archtest tooling).

Package contractpath provides the single source of truth for converting a contract ID to its module-relative generated package path.

Package csvparam parses comma-separated flag and query parameter values.

Package ctxcancel provides shared helpers for translating context cancellation surfaced from IO operations (DB scan, RPC call, message bus claim) into structured *errcode.Error values with the correct HTTP status for each ctx error variant:

Package ctxkeys provides typed context keys for generic observability and networking identifiers (correlation, trace, span, request, real IP) propagated through context.Context.

Package ctxutil provides small context.Context helpers for crossing cancellation boundaries that the standard library does not directly model.

Package errcode provides structured error codes for the GoCell framework.

Package errcodetest provides typed assertion funnels for errcode-bearing test paths.

Package fspath holds the single, symlink-aware root-containment predicate shared across the codebase: IsWithinRoot reports whether a target path resolves inside a root, and EvalExistingPrefix resolves the longest existing ancestor of a not-yet-existing path.

Package httputil provides shared HTTP response helpers for GoCell handlers, including JSON success/error writers and the standard response envelope.

Package idutil provides shared ID validation and generation for observability-safe identifiers across kernel/ and runtime/ layers.

Package logutil provides shared helpers for safely emitting user-controlled or network-derived strings through structured logging (slog).

Package migration holds the layer-free database-migration value types shared across all GoCell layers.

Package netutil provides shared network address utilities for the GoCell framework.

Package observability holds tiny shared helpers used across kernel/, runtime/ and adapters/ for emitting structured signals safely.

Package panicregister provides the only approved way to panic in GoCell production code.

Package pathsafe is the single funnel for scaffold/codegen file writes.

Package pgquery provides PostgreSQL helpers: SQL query building (Builder) and generic PG SQLSTATE wire-error classification (IsUniqueViolation / IsForeignKeyViolation).

Package pgrepoapproved provides the proof-of-authorization token that pgexec.ExecDirect requires as its first argument.

Package projection is the PEP-side (policy enforcement point) column-masking framework for the GoCell data-permission model.

Package redaction provides fail-closed scrubbing of sensitive substrings in error messages and free-form strings before they reach observability backends (OTel span attributes, audit logs, last_error storage columns).

Package scaffoldid is the single source of truth for typed scaffold identifier validation across the project.

Package securecookie encodes and decodes cookie values with HMAC-SHA256 signing and optional AES-GCM encryption using Go standard library crypto only.

Package secutil provides security utility helpers shared across GoCell adapters.

Package spiffeid provides a sealed SPIFFE-ID type identifying a GoCell cell at the transport (mTLS) layer.

Package tenant holds the layer-free tenancy value types shared across all GoCell layers: the TenantID sealed newtype (the multi-tenant isolation boundary identifier) and the RowScope authorization obligation enum.

Package errutil provides test-only helpers for inspecting joined error trees.

Package fileutil exports file I/O helpers for GoCell tests.

Package nettest is the sanctioned funnel for httptest.NewServer, httptest.NewTLSServer and httptest.NewUnstartedServer in packages that are locked by the SANDBOX-HTTPTEST-TCP-FUNNEL-01 archtest.

Package slogcapture is the single sanctioned holder of test-scope process-global slog mutation.

Package sloghelper provides test helpers for asserting slog JSON output.

Package testtime exports the canonical timeout / poll-interval constants used across GoCell test code.

Package testwait provides typed test-wait markers that replace bare require.Eventually / assert.Eventually polling.

Package validation provides field-level input validation helpers that return structured errcode errors suitable for HTTP handlers and service- layer preconditions.

Package yamlsafe provides a typed YAML scalar that safely round-trips through plain-style YAML emission.

Package audit centralizes bootstrap-period audit-chain helpers used by auditcore's auditappendbootstrap slice handler.

Package ledger provides a typed Protocol primitive and Store interface for append-only, HMAC-linked audit chains.

Package storetest provides a reusable Protocol-driven contract test suite for ledger.Store implementations.

ref: go-kratos/kratos middleware/auth/auth.go — auth middleware pattern Adopted: middleware wrapping pattern, Claims extraction from context.

Package config is the production wiring entrypoint for runtime/auth components.

Package credentialfence is the sealed source of the credential-invalidation FenceToken — a capability proof that authorizes calls to the three credential mutation methods (session.Store.RevokeForSubject / refresh.Store.RevokeUser / ports.UserRepository.BumpAuthzEpoch).

Package keystest provides RSA / HMAC key fixtures for tests that exercise the auth subsystem (JWT issue/verify, HMAC service-token rings, OIDC stubs).

This file declares the two public error sentinels for refresh.Store.

Package memstore provides an in-memory implementation of refresh.Store.

Package storetest provides a reusable contract test suite for refresh.Store implementations.

Package session declares the typed-Go-heavy Protocol primitive that bundles session-related protocol decisions for accesscore (and any future cell that owns server-side session state).

Package sessiontest provides test helpers for code that depends on runtime/auth/session.

Package storetest provides a reusable Protocol-driven contract test suite for session.Store implementations.

Package bootstrap orchestrates the full GoCell application lifecycle: config loading, assembly init/start, HTTP serving, event subscriptions, background workers, and graceful shutdown.

Package capability defines GoCell capability providers: assembly-level shared infrastructure resources (postgres pool, redis client, ...) provisioned once by the composition root and injected into every consuming cell module.

Package certlifecycle is the reusable server-side certificate-lifecycle reconcile.Reconciler.

Package certsigning is the framework's certificate-signing control-plane seam (Epic #1895 US2 PR-5 #1901): the CA signing interface, a protocol-agnostic request model, and the single mint funnel for device certificates.

Package pdpauthz provides a PDP-backed implementation of certsigning.Authorizer.

Package command wires kernel command workers (queue discovery + dispatch registry) into the runtime.

Package composition provides the public Composition Root abstraction for GoCell assemblies.

Package config provides a Config interface with YAML + environment variable loading.

Package crypto provides the KeyProvider abstraction and implementations for encrypting sensitive values at the repository boundary.

Package catalog — build.go: BuildDocument and all entity/filter helpers.

Package distlock defines the provider-neutral distributed-lock contract for the GoCell runtime layer.

Package locktest provides a controllable in-memory Driver implementation and a conformance test suite for use in unit tests.

Package eventbus provides an in-memory implementation of kernel/outbox Publisher and Subscriber for development and testing.

Package eventrouter provides a Router that separates event subscription declaration from execution.

Package interceptor provides the gRPC unary and streaming server interceptor chains that align the gRPC transport with the existing HTTP middleware stack (runtime/http/middleware): RequestID, CellAttribution, Tracing, AccessLog, Metrics, RateLimit, CircuitBreaker, Auth, ErrcodeMap, and Recovery.

Package cellmw provides reusable RouteHandler wrappers for use in cell slice handlers.

Package devtools provides framework-internal HTTP routes that expose project catalog metadata (cells, slices, contracts, journeys, assemblies, actors) plus optional cell-level and package-level dependency graphs to admin-authenticated clients.

Package health provides /healthz (liveness) and /readyz (readiness) HTTP endpoints.

Package healthtest provides shared test helpers for packages that need to assert on the slog channel-d verbose breakdown emitted by runtime/http/health.Handler.

Package probequery parses query parameters that gate health-probe verbose output.

Package healthtest provides test-only helpers for probe authors writing against the runtime/http/health API.

Package idempotency provides HTTP-layer idempotency primitives for GoCell.

Package idempotencytest provides a reusable conformance suite for implementations of idemhttp.Store.

Package middleware provides chi-compatible HTTP middleware for GoCell applications.

Package router provides a chi-based HTTP router that implements kernel/cell.RouteMux with default middleware and automatic health/metrics endpoint registration.

Package tlsutil builds server-side TLS configurations for GoCell HTTP listeners.

Package tlsutiltest is the single sanctioned source of self-signed mTLS cert material for GoCell tests: a self-signed ECDSA P-256 root CA and the cell / transport leaves it issues (SPIFFE-URI / DNS / IP SANs, ServerAuth / ClientAuth EKU).

Package lifecycle provides a runtime read-surface over the maturity lifecycle (kernel/cellvocab.CellLifecycle) of the cells composing a running assembly.

Package healthz provides the default in-memory kernel/healthz.Aggregator implementation for GoCell.

Package healthztest provides shared test helpers for kernel/healthz.Aggregator implementations.

Package logging provides a slog.Handler that enriches log records with trace_id, span_id, request_id, correlation_id, and cell_id from the request context.

Package metrics provides HTTP request instrumentation interfaces and an in-memory implementation.

Package metricstest provides a shared conformance suite for implementations of metrics.Collector.

Package tracingtest provides an in-process, stdlib-only Tracer fixture for tests.

Package outbox provides the runtime-layer Store interface and relay worker for transactional outbox delivery.

Package outboxtest provides a public in-memory Store implementation and a Store conformance test suite for use in unit tests.

Package saga (see doc.go for the package narrative) is the runtime engine that drives saga instances forward.

Package executor provides the step-level execution engine for saga instances.

Package tailer implements the saga-journal projection catch-up tailing live driver (EPIC #1609 PR-04).

Package schemavalidate provides transport-neutral JSON Schema validation for generated code at untrusted wire boundaries.

Package shutdown provides graceful shutdown support by listening for SIGINT/SIGTERM signals with a configurable timeout and ordered teardown.

Package cas provides a typed-Go-heavy Protocol primitive for compare-and-swap (CAS) optimistic concurrency control.

Package syshealth projects the runtime's existing health primitives — the kernel healthz.Aggregator probe snapshot and the [assembly.CoreAssembly] per-cell view — into an operator-facing, per-cell aggregate (#1860).

Package sysinfo projects process-local build/runtime metadata into the operator-facing http.admin.system.v1 contract served by syscore.

Package transport is the framework's location-transparent sync (http) contract transport seam (Epic #1423 US4 #1963).

Package webhook implements the inbound-webhook receiver runtime for GoCell.

Package dispatch wires outbound-webhook dispatchers into the event router.

Package websocket provides a Hub-based WebSocket connection manager with signal-first broadcasting, ping/pong health checks, and graceful shutdown.

Package worker provides a Worker interface and WorkerGroup for managing concurrent background workers with graceful lifecycle control.