cellvocab

type CellLifecycle ¶

type CellLifecycle string

CellLifecycle is the governance maturity lifecycle of a Cell or Slice, declared in cell.yaml / slice.yaml `lifecycle`. It is orthogonal to three other "lifecycle" concepts in the codebase:

• the runtime cellState (New/Initialized/Started/Stopped) in kernel/cell — where a cell is in its boot/shutdown sequence;
• cellvocab.ContractLifecycle (draft/active/deprecated) — a Contract's wire-stability state;
• JourneyMeta.Lifecycle (active/experimental) — a Journey's delivery status.

CellLifecycle is a maturity axis (how production-ready the cell/slice is), not a runtime state machine: a cell.yaml declares one static lifecycle value, and there is no runtime "lifecycle transition" event (advancing maturity is a human edit). It is therefore a plain ordered enum — there is deliberately no transition map / Transition() here. The ordering (cellLifecycles) feeds CellLifecycleRank, which the CELL-LIFECYCLE-01 governance rule uses for the slice≤cell consistency check.

ref: Team Topologies maturity vocabulary (experimental → asset). ref: docs/architecture/202605262100-adr-cell-slice-lifecycle-phase.md §Decision-A (why no transition map).

const (
	CellLifecycleExperimental CellLifecycle = "experimental" // early development, may change/disappear
	CellLifecycleCandidate    CellLifecycle = "candidate"    // stabilizing, approaching production use
	CellLifecycleAsset        CellLifecycle = "asset"        // stable, production-relied-upon
	CellLifecycleMaintenance  CellLifecycle = "maintenance"  // stable but no longer actively evolved
	CellLifecycleRetired      CellLifecycle = "retired"      // end of life
)

func AllCellLifecycles() [5]CellLifecycle

func ParseCellLifecycle(s string) (CellLifecycle, error)

func (p CellLifecycle) Rank() int

type CellType ¶

type CellType string

CellType classifies a Cell's architectural role.

const (
	CellTypeCore    CellType = "core"
	CellTypeEdge    CellType = "edge"
	CellTypeSupport CellType = "support"
)

func ParseCellType(s string) (CellType, error)

type ContractKind ¶

type ContractKind string

ContractKind classifies the communication pattern of a Contract.

const (
	ContractHTTP       ContractKind = "http"
	ContractEvent      ContractKind = "event"
	ContractCommand    ContractKind = "command"
	ContractProjection ContractKind = "projection"
	ContractWebhook    ContractKind = "webhook"
	ContractGRPC       ContractKind = "grpc"
	ContractSaga       ContractKind = "saga"
)

func AllContractKinds() []ContractKind

func ParseContractKind(s string) (ContractKind, error)

type ContractLifecycle ¶

type ContractLifecycle string

ContractLifecycle represents the wire-stability governance state of a Contract (draft / active / deprecated). This is orthogonal to CellLifecycle (the cell/slice maturity axis) and JourneyMeta.Lifecycle (journey delivery status).

const (
	ContractLifecycleDraft      ContractLifecycle = "draft"
	ContractLifecycleActive     ContractLifecycle = "active"
	ContractLifecycleDeprecated ContractLifecycle = "deprecated"
)

func ParseContractLifecycle(s string) (ContractLifecycle, error)

type ContractRole ¶

type ContractRole string

ContractRole describes how a Slice participates in a Contract.

const (
	RoleServe     ContractRole = "serve"
	RoleCall      ContractRole = "call"
	RolePublish   ContractRole = "publish"
	RoleSubscribe ContractRole = "subscribe"
	RoleHandle    ContractRole = "handle"
	RoleInvoke    ContractRole = "invoke"
	RoleProvide   ContractRole = "provide"
	RoleRead      ContractRole = "read"
	// RoleOrchestrate is the saga provider role: the cell that owns and drives
	// the saga definition (declares the contract via endpoints.server). Saga has
	// no consumer-side role — participation is one orchestrating cell per saga.
	RoleOrchestrate ContractRole = "orchestrate"
	// Webhook roles: a cell either receives inbound webhooks (consumer-side) or
	// dispatches outbound webhooks (provider-side). See ValidRolesForKind.
	RoleWebhookReceive  ContractRole = "webhook-receive"
	RoleWebhookDispatch ContractRole = "webhook-dispatch"
)

func AllContractRoles() []ContractRole

func ParseContractRole(s string) (ContractRole, error)

func ValidRolesForKind(kind ContractKind) []ContractRole

http:       serve, call
event:      publish, subscribe
command:    handle, invoke
projection: provide, read
webhook:    webhook-receive, webhook-dispatch
grpc:       serve, call
saga:       orchestrate

type Level ¶

type Level int

Level represents the consistency level (L0-L4) of a Cell or Contract.

const (
	L0 Level = iota // LocalOnly
	L1              // LocalTx
	L2              // OutboxFact
	L3              // WorkflowEventual
	L4              // DeviceLatent
)

func ParseLevel(s string) (Level, error)

func (l Level) String() string

type ProjectionApply ¶

type ProjectionApply func(ctx context.Context, event ProjectionEvent) error

ProjectionApply is the business event→state projection hook: given a consumed ProjectionEvent, mutate the read-model within the ambient transaction carried by ctx. It is the single underlying type aliased by both kernel/cell.ProjectionApply (the cell-local registry surface) and kernel/projection.Apply (the harness surface) so the bootstrap drain passes a recorded hook to Coordinator.Subscribe with no named-type conversion. The full behavioral contract (tx semantics, transient vs permanent error vocabulary) lives on the projection.Apply alias godoc.

type ProjectionEvent ¶

type ProjectionEvent interface {
	// EventID is the event's identifier, which MUST be unique across the entire
	// replay source (not merely within a Stream): the harness Cursor resolves a
	// stable position by matching EventID over the whole source (mem scans all
	// entries; PG does `SELECT seq … WHERE id = $1`), so two distinct events
	// sharing an EventID would resolve to the same position and corrupt the
	// checkpoint. outbox.Entry satisfies this with its global UUID; a future
	// saga-journal carrier (PR-03) must likewise expose a source-global-unique id.
	EventID() string
	// Payload is the raw event body JSON consumed by the business Apply hook.
	Payload() []byte
	// OccurredAt is the domain timestamp (used for the replay-lag metric).
	OccurredAt() time.Time
	// Stream is the routing/topic equivalent (outbox: RoutingTopic); the harness
	// filters a projection to its subscribed stream by comparing against the spec.
	Stream() string
	// RestoreContext returns a context with the event's ambient identity
	// installed before Apply runs (outbox: observability + principal restore). It
	// must be idempotent and must not strip an ambient transaction carried by ctx.
	RestoreContext(ctx context.Context) context.Context
}

ProjectionEvent is the minimal typed read-only carrier consumed by the projection harness (kernel/projection): Apply, ReplaySource.Replay's callback, and Cursor.Position all carry a ProjectionEvent rather than the concrete kernel/outbox.Entry. Generalizing the carrier lets a saga-journal event source (EPIC #1609 PR-03) and the outbox event source flow through one typed funnel with no dual outbox.Entry-typed path.

Why this lives in cellvocab ¶

kernel/projection imports kernel/cell (its Coordinator references cell.SubscriptionOption), and kernel/cell declares ProjectionApply — the cell-local mirror of projection.Apply — so the carrier type must live in a package BOTH import without forming a cycle. cellvocab is that leaf (it imports nothing in kernel/): both kernel/cell and kernel/projection alias these types, and kernel/outbox can import cellvocab for its `var _ ProjectionEvent = Entry{}` compile assertion (kernel/cell cannot host the interface for that assertion — kernel/cell already imports kernel/outbox, so the reverse import would be a cycle). The ADR (#1609 §4.1) named the package kernel/projection; the cell↔projection cycle makes that infeasible — see the §4.1/§6 amendment.

Not sealed (by design) ¶

All methods are exported and any package may implement ProjectionEvent — the carrier source is intentionally open so the PR-03 saga carrier can implement it too. It is NOT a sealed/forge-proof funnel; forge protection lives in the wiring layer (the Tailer feeding Apply solely from the sealed journal, ADR §5). Enforcement that public projection APIs carry ProjectionEvent (not the concrete outbox.Entry) is the type system plus archtest PROJECTION-EVENT-CARRIER-TYPED-01.

EventID and Stream are the polymorphic renames of the outbox concepts (outbox.Entry.ID / outbox.Entry.RoutingTopic), chosen so the saga carrier's distinct identity/stream semantics are unambiguous on the shared interface.

type ProjectionResetHook ¶

type ProjectionResetHook func(ctx context.Context) error

ProjectionResetHook is the optional rebuild Reset-phase hook (clear the read-model before replay). nil is valid. Aliased by kernel/cell.ProjectionResetHook and kernel/projection.OnReset.

type Transport ¶

type Transport string

Transport names the wire protocol a contract binds to. A contract declares a non-empty SET of sanctioned transports via contract.yaml `transports:` (defaulted per-kind by the parser when omitted); contractgen derives the generated ContractSpec.Transport as the primary (transports[0]). This typed const set is the SINGLE SOURCE for the contract.schema.json transports enum (byte-locked by TestSchemaConstantsMatchSchemaLiterals#transportEnum), governance FMT-39, and runtime metadata.IsKnownTransport. Unlike AsyncAPI's open `protocol` string, GoCell's transport set is closed: a platform-owned kernel fails fast on an unknown transport rather than discovering it at runtime (mirrors k8s core/v1 Protocol +enum). ref: kubernetes/api core/v1/types.go (Protocol +enum); asyncapi/spec server.protocol.

const (
	TransportAMQP     Transport = "amqp"
	TransportMQTT     Transport = "mqtt"
	TransportInternal Transport = "internal"
	TransportHTTP     Transport = "http"
	TransportGRPC     Transport = "grpc"
)

func AllTransports() []Transport

func ParseTransport(s string) (Transport, error)

type WebhookDirection ¶

type WebhookDirection string

WebhookDirection is the flow direction of a kind=webhook contract: inbound (external → cell, receiver-side) or outbound (cell → external, dispatcher-side). Single source shared by kernel/metadata (parser webhook derivation) and kernel/governance (FMT-38), so the direction string never drifts across layers.

const (
	DirectionInbound  WebhookDirection = "inbound"
	DirectionOutbound WebhookDirection = "outbound"
)