cellgen

type CellArtifact struct {
	// Kind is "cell-gen" or "slice-gen".
	Kind string
	// RelPath is the project-relative path the file would be written to,
	// e.g. "examples/todoorder/cells/ordercell/cell_gen.go".
	RelPath string
	// Content is the rendered, formatted, goimports-processed bytes.
	Content []byte
}

type CellFieldIndex struct {
	// contains filtered or unexported fields
}

type CellGenSpec struct {
	// Package is the Go package name for cell_gen.go.
	Package string
	// StructName is the receiver type (CellMeta.GoStructName).
	StructName string
	// CellID is CellMeta.ID — used for fmt.Errorf wrapping in Init.
	CellID string
	// ConsumerGroupDefault is the cell ID, used when a SubscriptionGenSpec
	// omits its ConsumerGroup.
	ConsumerGroupDefault string
	// SourceFile is the project-relative path of the cell.yaml that drove
	// generation (e.g. "examples/todoorder/cells/ordercell/cell.yaml").
	// Rendered into the file header as "// Source: <SourceFile>" so that
	// readers of the generated file can locate the authoritative YAML.
	SourceFile string
	// RenderedMetaLiteral is the pre-rendered Go source literal for the cell's
	// metadata, of the form "&metadata.CellMeta{...}". BuildCellSpec calls
	// renderCellMetaLiteral(cell) at spec build time and assigns the result;
	// cell.tmpl emits the string verbatim into
	// `var cellMeta = {{ .RenderedMetaLiteral }}`.
	//
	// CELLGEN-LITERAL-FUNNEL-02 Hard source (highest type-system grade):
	// cell.tmpl cannot reach *metadata.CellMeta because CellGenSpec does not
	// expose it. Hand-enumeration of CellMeta fields in the template is
	// structurally unreachable — there is no data source to access. Any
	// attempt to bypass the reflect-driven renderer must change the type of
	// this field, which is a public API change and therefore review-visible.
	RenderedMetaLiteral string
	// RouteGroups holds the listener-aggregated route mounts. Each entry
	// emits one reg.RouteGroup() call.
	RouteGroups []RouteGroupGenSpec
	// Subscriptions holds the per-slice event subscriptions. Each entry
	// emits one reg.Subscribe() call (and one specEvent... var declaration).
	Subscriptions []SubscriptionGenSpec
	// WebhookReceivers holds the per-slice inbound webhook registrations.
	// Each entry emits one reg.RegisterWebhookReceiver() call.
	WebhookReceivers []WebhookReceiverGenSpec
	// WebhookDispatches holds the per-slice outbound webhook registrations.
	// Each entry emits one reg.RegisterWebhookDispatch() call.
	WebhookDispatches []WebhookDispatchGenSpec
	// Projections holds the per-slice CQRS projection registrations derived from
	// subscribe CUs that carry a non-empty projection: field. Each entry emits
	// one reg.RegisterProjection() call.
	Projections []ProjectionGenSpec
	// GrpcServices holds the per-slice gRPC serve registrations derived from
	// contractUsages[role=serve] with kind=grpc. Each entry emits one
	// reg.GRPCService() call.
	GrpcServices []GrpcServiceGenSpec
	// HTTPMethodPermissions holds the cell-level (contractID → ABAC action) pairs
	// derived from each served HTTP contract's endpoints.http.permission overlay
	// (#2205), sorted by contract id for deterministic golden output. When non-empty,
	// cell.tmpl renders a package-level resolver var
	// `<cell>HTTPResolver = auth.NewStaticMethodPolicyResolver(map[string]string{...})`
	// (the HTTP transport's authz.MethodPolicyResolver, sibling of the gRPC
	// registrar) that cell_init.go injects into the contract-derived slice handlers.
	// Empty → no contract-derived HTTP gates in this cell; the resolver var and its
	// runtime/auth import are omitted. MethodPermission.FullMethod holds the contract
	// id here (not a gRPC method name); the field is reused to avoid a near-duplicate
	// string→string pair type.
	HTTPMethodPermissions []MethodPermission
}

type GrpcServiceGenSpec struct {
	// ContractID is the gRPC contract id, e.g. "grpc.device.command.v1".
	ContractID string
	// SliceID identifies the slice owning the server implementation — primary
	// sort key (mirrors SubscriptionGenSpec).
	SliceID string
	// HandlerField is the cell struct field name holding the gRPC server
	// implementation, e.g. "commandServer".
	HandlerField string
	// RegisterFunc is the protoc-gen-go-grpc generated registration function,
	// e.g. "RegisterDeviceCommandServiceServer". Derived from the last
	// dot-segment of the proto service FQN + "Server".
	RegisterFunc string
	// ListenerConst is the Go constant reference for the gRPC listener;
	// always "cell.PrimaryListener" for grpc-serve (rendered verbatim).
	ListenerConst string
	// ProtoRel is the contracts-relative path of the .proto file,
	// e.g. "contracts/grpc/device/command/v1/device_command.proto".
	// Used by EnrichGrpcServicesWithProtoInfo to resolve the import path.
	ProtoRel string
	// Service is the proto fully-qualified service name,
	// e.g. "device.command.v1.DeviceCommandService".
	// Retained for proto-info resolution (EnrichGrpcServicesWithProtoInfo passes
	// it to contractgen.ReadProtoServiceInfo) and is NOT rendered directly into
	// cell_gen.go; only RegisterFunc/PbAlias/HandlerField/ContractID/ListenerConst
	// appear in the generated output.
	Service string
	// PbImportPath is the Go import path of the generated proto package.
	// Populated by EnrichGrpcServicesWithProtoInfo (post-build, FS-derived).
	PbImportPath string
	// PbAlias is the import alias for PbImportPath in cell_gen.go,
	// e.g. "grpc0", "grpc1". Set by EnrichGrpcServicesWithProtoInfo.
	PbAlias string
	// PublicMethods lists the FULL method names (/{Service}/{Method}) marked
	// JWT-exempt by the contract's endpoints.grpc.methods[] overlay (the
	// public:true entries, #1675). Composed in buildGrpcServiceSpecFromCU from the
	// overlay + Service FQN; rendered into the generated GRPCServiceSpec literal so
	// the runtime registrar aggregates them into the auth interceptor's bypass set.
	// Empty → no public methods (the fail-closed default). Referential integrity
	// (each name ∈ proto method set) is enforced by the contractgen pre-pass.
	PublicMethods []string
	// MethodPermissions lists the (FULL method name → ABAC action) pairs derived
	// from the contract's endpoints.grpc.methods[] permission entries (#2008),
	// sorted by full method name for deterministic golden output. Rendered into the
	// generated GRPCServiceSpec literal as a map[string]string the runtime registrar
	// resolves to sealed authz.Permissions for the PDP gate. Empty → no permission
	// gates; the completeness pre-pass rejects a non-public proto method with no
	// permission, so empty means the service is all-public or has no authed RPCs.
	MethodPermissions []MethodPermission
	// MethodResources lists the (FULL method name → request message field name) pairs
	// derived from the contract's endpoints.grpc.methods[] resource entries (#2207),
	// sorted by full method name for deterministic golden output. Rendered into the
	// generated GRPCServiceSpec literal as a map[string]string. Empty → no owner-scoped
	// per-message resource extraction; all methods use fullMethod as PDP resource (coarse).
	MethodResources []MethodResource
	// PasswordResetExemptMethods lists the FULL method names (/{Service}/{Method})
	// marked exempt from the password-reset gate by the contract's
	// endpoints.grpc.methods[] overlay (the passwordResetExempt:true entries, #1382).
	// Composed in buildGrpcServiceSpecFromCU from the overlay + Service FQN;
	// rendered into the generated GRPCServiceSpec literal so the runtime registrar
	// aggregates them into the auth interceptor's exempt set.
	// Empty → no exempt methods (the fail-closed default). Referential integrity
	// (each name ∈ proto method set) is enforced by the contractgen pre-pass.
	PasswordResetExemptMethods []string
}

type HealthzGenSpec struct {
	// Package is the Go package name for healthz_gen.go (= CellMeta.Dir).
	Package string
	// CellID is the cell id — used to construct the ProbeRepoReady constant
	// value ("<cellid>_repo_ready") and the godoc comment.
	CellID string
	// SourceFile is the project-relative path of the cell.yaml that drove
	// generation. Rendered into the file header as "// Source: <SourceFile>".
	SourceFile string
}

type MethodPermission struct {
	// FullMethod is the /{Service}/{Method} name, e.g.
	// "/device.command.v1.DeviceCommandService/IssueCommand".
	FullMethod string
	// Permission is the ABAC action string, e.g. "device:command".
	Permission string
}

type MethodResource struct {
	// FullMethod is the /{Service}/{Method} name, e.g.
	// "/device.command.v1.DeviceCommandService/WatchCommands".
	FullMethod string
	// Field is the proto request message field name (snake_case), e.g. "device_id".
	// The interceptor extracts it via protoreflect and canonicalizes the value.
	Field string
}

type Options struct {
	// DryRun emits ActionWouldWrite without filesystem mutation.
	DryRun bool
	// Verify diffs the rendered content against disk and reports drift.
	// Mutually exclusive with DryRun at the CLI layer; combining them here
	// is harmless (Verify dominates — no write either way).
	Verify bool
	// OnlyCell, when non-empty, restricts generation to a single cell id.
	// Empty = generate for every cell in project.
	OnlyCell string
	// ModulePath is the consuming repo's Go module path (from its go.mod),
	// threaded to the formatter so generated files group module-local imports
	// the way the target repo's golangci-lint gate expects (#1083). Required:
	// Generate rejects an empty ModulePath. The CLI resolves it via
	// resolveModule (flag-or-go.mod); RenderCellArtifacts resolves it from root.
	ModulePath string
}

type ProjectionGenSpec struct {
	ContractID   string // event contract id (input stream); Spec.Kind=="event"
	SliceID      string // primary sort key (mirrors SubscriptionGenSpec)
	ProjectionID string // snake_case probe-name; half of checkpoint key
	ApplyExpr    string // dotted apply ref, e.g. "c.projSvc.HandleOrderCreated"
	OnResetExpr  string // dotted onReset ref or "" (renders nil)
	// Source selects the projection input stream. "" or "outbox" → outbox path
	// (per-event-contract NewProjectionRequest with a SpecPackage/SpecAlias import);
	// "saga-journal" → saga path (cell.NewSagaJournalProjectionRequest, no event Spec,
	// no OnReset, SpecPackage/SpecAlias stay empty).
	Source string
	// Populated by EnrichProjectionsWithModulePath (post-build, FS-derived);
	// stays empty for saga-journal sources (no per-contract import):
	SpecPackage string // import path of the generated event contract package
	SpecAlias   string // "proj0","proj1",... unique import alias
}

type Result struct {
	// Generated lists files that were written, would-have-been-written
	// (DryRun), or remain unchanged (Unchanged).
	Generated []string
	// Drifted lists files whose disk content differs from the freshly
	// rendered content (Verify mode).
	Drifted []string
}

type RouteGroupGenSpec struct {
	// ListenerConst is the Go constant reference for the listener
	// (e.g. "cell.PrimaryListener"). Rendered verbatim.
	ListenerConst string
	// Prefix is the URL prefix mounted on the listener (e.g. "/api/v1").
	Prefix string
	// SubRoutes groups handler mounts by subPath. A nil/empty SubPath
	// means the handler attaches directly to the prefix.
	SubRoutes []RouteSubGroup
}

type RouteSliceMount struct {
	HandlerField string
	// Method is the registration method on the handler. Zero value is unsafe —
	// populate via BuildCellSpec which substitutes "RegisterRoutes" when the
	// YAML omits it.
	Method string
}

type RouteSubGroup struct {
	// SubPath is the path relative to the listener prefix. Empty SubPath
	// indicates direct attachment (no mux.Route wrapper).
	SubPath string
	// Mounts lists the slice handler invocations inside the closure,
	// preserving declaration order across slices for diff stability.
	Mounts []RouteSliceMount
}

type ScaffoldSpec struct {
	// CellID is the cell identifier (e.g. "foocell"). Typed so the
	// (^[a-z][a-z0-9]+$) constraint is established at construction time via
	// scaffoldid.Parse — callers cannot supply an unvalidated raw string
	// (SCAFFOLD-INPUT-CONTRACT-TYPED-ID-01).
	CellID scaffoldid.ScaffoldID
	// StructName is the Go struct name (e.g. "FooCell").
	StructName string
	// Package is the Go package name (e.g. "foocell").
	Package string
	// ModulePath is the Go module path (e.g. "github.com/ghbvf/gocell").
	ModulePath string
	// OwnerTeam is the team responsible for this cell (e.g. "platform").
	// Required. Written as-is to cell.yaml owner.team.
	OwnerTeam string
	// OwnerRole is the ownership role for this cell (e.g. "cell-owner").
	// Required. Written as-is to cell.yaml owner.role.
	OwnerRole string
	// Type is the cell type. Must be one of validCellTypes.
	// Defaults to "core" when empty.
	Type string
	// ConsistencyLevel is the cell consistency level. Must be one of validConsistencyLevels.
	// Defaults to "L1" when empty.
	ConsistencyLevel string
	// SkipGenerate, when true, skips the appended cellgen/contractgen derived
	// artifacts from PlanCellBundleScaffold. The resulting plan contains only
	// skeleton files. Mirrors assembly.AssemblyScaffoldSpec.SkipGenerate semantics.
	SkipGenerate bool
	// WithHTTP, WithEvents, WithBoth control K#09 ScaffoldCellBundle's contract
	// variant. WithHTTP produces an HTTP request/response contract (default
	// when none of the three flags are set). WithEvents produces an event
	// payload/headers contract. WithBoth produces both.
	WithHTTP   bool
	WithEvents bool
	WithBoth   bool
}

type SliceGenSpec struct {
	// Package is the Go package name for slice_gen.go.
	Package string
	// CellID identifies the parent cell (used in interface comment).
	CellID string
	// SliceID identifies this slice (used in interface comment).
	SliceID string
	// SourceFile is the project-relative path of the slice.yaml that drove
	// generation (e.g. "examples/todoorder/cells/ordercell/slices/ordercreate/slice.yaml").
	// Rendered into the file header as "// Source: <SourceFile>".
	SourceFile string
	// Handlers lists the handler methods the slice's service must provide.
	// Order is deterministic to keep generated diff stable.
	Handlers []SliceHandlerSpec
	// RenderedMetaLiteral is the pre-rendered Go source literal for the
	// slice's metadata.SliceMeta value (the typed projection of slice.yaml).
	// BuildSliceSpec invokes renderSliceMetaLiteral(s) at spec build time and
	// assigns the result; slice.tmpl emits `var sliceMeta = {{ .RenderedMetaLiteral }}`.
	RenderedMetaLiteral string
}

type SliceHandlerSpec struct {
	// MethodName is the Go method name, e.g. "HandleOrderCreated".
	MethodName string
	// ContractID is the contract that triggers the handler — included as a
	// godoc reference on the generated interface method.
	ContractID string
}

type SubscriptionGenSpec struct {
	// ContractID is the full event contract id, e.g. "event.config.entry-upserted.v1".
	ContractID string
	// SliceID identifies the slice owning the handler — used for
	// cell.WithSubscriptionSliceID().
	SliceID string
	// HandlerExpr is the dotted handler reference e.g. "c.subscribeSvc.HandleEntryUpserted".
	HandlerExpr string
	// ConsumerGroup is the broker consumer-group identifier. When empty
	// the renderer falls back to CellGenSpec.ConsumerGroupDefault.
	ConsumerGroup string
	// SubscriptionPackage is the Go import path for the generated contract package
	// that provides NewSubscription, e.g.
	// "github.com/ghbvf/gocell/generated/contracts/event/order-created/v1".
	// Populated by BuildCellSpec from the contract id via contractIDToImportPath.
	SubscriptionPackage string
	// SubscriptionAlias is the import alias used in cell_gen.go for SubscriptionPackage
	// (e.g. "sub0", "sub1") to avoid package name collisions between multiple v1 packages.
	SubscriptionAlias string
}

type WebhookDispatchGenSpec struct {
	// ContractID is the webhook contract id, e.g. "webhook.shopify.orders.v1".
	ContractID string
	// SliceID identifies the slice owning the selector — the primary sort key so
	// output ordering is deterministic even when one contract is wired by more
	// than one slice (mirrors SubscriptionGenSpec).
	SliceID string
	// SourceID is the signing-secret source (slice.yaml contractUsages.sourceID).
	SourceID string
	// SelectorExpr is the dotted selector reference, e.g. "c.shopifySvc.ShopifyTarget".
	SelectorExpr string
}

type WebhookReceiverGenSpec struct {
	// ContractID is the webhook contract id, e.g. "webhook.stripe.payment-events.v1".
	ContractID string
	// SliceID identifies the slice owning the handler — the primary sort key so
	// output ordering is deterministic even when one contract is wired by more
	// than one slice (mirrors SubscriptionGenSpec).
	SliceID string
	// SourceID is the secret-isolation key (slice.yaml contractUsages.sourceID).
	SourceID string
	// HandlerExpr is the dotted handler reference, e.g. "c.stripeSvc.HandleStripeEvent".
	HandlerExpr string

	// Runtime configuration baked from contract.yaml at code-generation time.
	// PathPattern is the HTTP path the receiver runtime mounts
	// (contract.yaml endpoints.inbound.pathPattern).
	PathPattern string
	// DeliveryIDHeader is the HTTP header name carrying the per-delivery
	// identifier (contract.yaml signature.deliveryIDHeader).
	DeliveryIDHeader string
	// TimestampHeader is the HTTP header name carrying the unix-seconds
	// timestamp (contract.yaml signature.timestampHeader).
	TimestampHeader string
	// SignatureHeader is the HTTP header name carrying the HMAC signature tokens
	// (contract.yaml signature.signatureHeader).
	SignatureHeader string
	// ToleranceSeconds is the bidirectional timestamp window in seconds
	// (contract.yaml signature.toleranceSeconds). Must be > 0.
	ToleranceSeconds int64
	// MaxBodyBytes is the maximum accepted request body size in bytes
	// (contract.yaml payload.maxBodyBytes). Must be > 0.
	MaxBodyBytes int64
}