codegen

type AppField struct {
	Name string
	Type string

	// Placeholder is the target type the AppExtras field should be
	// tightened to once a sibling lane lands the real type. Set when
	// the field carries a `// forge:placeholder: <Type>` doc/inline
	// comment marker. Empty for fields without the marker.
	//
	// The annotation exists because parallel agents writing into
	// app_extras.go often need to declare a field whose typed Repository /
	// Client / Provider lives in a sibling lane that hasn't merged yet.
	// Typing the field as `any` keeps the build green; the placeholder
	// marker says "I know this is `any` — wire_gen should treat me as
	// <Type>, and lint should error until I'm tightened to <Type>".
	//
	// wire_gen renders a typed `resolve<Field>(app)` accessor when the
	// marker is present so call sites can consume the field as the
	// promised type rather than `any`. When the user finally tightens
	// the field declaration from `any` to <Type>, the accessor stays
	// correct (the type assertion is a no-op for a value already typed
	// as <Type>).
	Placeholder string
}

type AppFieldRef struct {
	DepsField string // e.g. "Repo"
}

type AuthTemplateData struct {
	Provider    string // "jwt", "api_key", "both"
	JWT         config.JWTConfig
	APIKey      config.APIKeyConfig
	Module      string
	SkipMethods []string // procedure names that don't require auth
}

type AuthzMethodData struct {
	Procedure     string   // full RPC procedure path, e.g. "/services.users.v1.UserService/CreateUser"
	RequiredRoles []string // roles that grant access (empty = any authenticated user)
	AuthRequired  bool     // whether auth is required for this method
	// AuthzCustom marks a method whose authorization is delegated to a
	// hand-written authorizer ((forge.v1.method).authz_custom). It carries no
	// role allow-list, so the template must NOT emit it with empty roles (that
	// reads as an any-authenticated grant). Instead the template emits it
	// FAIL-CLOSED — a sentinel "custom — see interceptor" role that no caller
	// holds — so the generated table can't be misread as a grant. The real
	// decision is enforced by the descriptor-driven RoleInterceptor + the
	// service's authorizer.go, never this table.
	AuthzCustom bool
	// Errors records the Connect/gRPC error codes the method may return,
	// derived from (forge.v1.method).errors. The template emits a
	// per-method entry in `methodErrors` so handler readers (including
	// LLMs) see the typed error contract alongside the role table.
	// Methods with no declared errors are omitted from the map.
	Errors []string
}

type AuthzTemplateData struct {
	Package     string            // Go package name, e.g. "users"
	ServiceName string            // proto service name, e.g. "UserService"
	Module      string            // Go module path
	Methods     []AuthzMethodData // per-method authorization data
}

type BootstrapComponentData struct {
	Name       string // e.g. "api", "cache", "email_sender"
	Package    string // e.g. "api" (Go package identifier — leaf of ImportPath for nested entries)
	ImportPath string // e.g. "api" or "mcp/database" (path under internal/, workers/, etc.)
	FieldName  string // e.g. "API" or "McpDatabase" (exported struct field, must be unique)
	VarName    string // e.g. "api" or "mcpDatabase" (unique lowerCamel local-var prefix in bootstrap)
	Fallible   bool   // true if New() returns (T, error)
	// Alias is the import alias used in bootstrap.go for this component's
	// Go package. Defaults to Package when there are no cross-role
	// collisions; gets a role-prefixed value (e.g. "svcBilling",
	// "pkgBilling") when a service Package matches an internal package
	// Package (or other cross-role pair). All bootstrap.go references
	// to the package's exported symbols must use Alias rather than
	// Package so the alias-rewrite is observed at every call site.
	Alias string
	// HasWebhooks is true when this service has webhooks declared in
	// forge.yaml. The bootstrap template uses this to emit a
	// `RegisterWebhookRoutes(mux, stack)` call after `RegisterHTTP(...)`,
	// so generated webhook routes get mounted on the mux without the user
	// having to hand-edit the user-owned `RegisterHTTP` body in
	// handlers/<svc>/service.go. Only populated for services; ignored
	// for packages, workers, and operators.
	HasWebhooks bool
	// HasLogger / HasConfig record whether this component's Deps struct
	// declares a Logger / Config field. The bootstrap template gates the
	// emission of those Deps-literal fields on these flags so a package
	// that doesn't consume them isn't forced to carry vestigial Logger /
	// Config fields just to keep the generated New(Deps{...}) call site
	// type-checking. Populated by inspectComponentDepsShape before
	// rendering; defaults to false (skip) when the source dir can't be
	// parsed (e.g. just-scaffolded component with no Deps yet).
	HasLogger bool
	HasConfig bool
	// AppFieldRefs lists Deps fields (other than Logger/Config) whose
	// names AND types match an AppExtras field. Bootstrap emits one
	// assignment per entry like `<DepsField>: app.<DepsField>`. Without
	// this, audit.New got only {Logger} even when audit.Deps.Repo and
	// app.Repo both existed — the package silently degraded (Log warn-
	// and-drops) until the next forge generate cycle. wire_gen has had
	// this logic for services; this brings packages to parity.
	AppFieldRefs []AppFieldRef
	// CanonicalAppField names the single App/AppExtras field whose
	// declared type is this internal package's Service interface (e.g.
	// AppExtras.DaemonService of type svcdaemon.Service). Populated by
	// inspectComponentDepsShape ONLY when the package's Deps struct has
	// at least one non-optional collaborator field that bootstrap cannot
	// auto-wire from App/AppExtras (no name match, or proven type
	// mismatch) — i.e. the construction is unexpressible from app
	// fields. When set, the bootstrap template emits
	//
	//	app.Packages.<FieldName> = app.<CanonicalAppField>
	//
	// instead of `<pkg>.New(<pkg>.Deps{...})`: user-owned setup.go
	// constructs the canonical, fully-wired instance (with deps that
	// have no AppExtras representation — inline URL builders,
	// env-derived strings, cross-package collaborators), and appkit
	// runs Setup BEFORE the package table, so the alias always observes
	// the setup.go assignment. Constructing a second instance here
	// instead would produce a half-built duplicate that panics in
	// validateDeps or silently no-ops — the cp-forge svcdaemon
	// hand-edit class (Deps.DaemonRepo/URLBuilder unwireable, boot
	// panic "Deps.DaemonRepo is required").
	//
	// Empty when: every Deps field auto-wires (keep constructing — the
	// enforcement/Checker shape), the only gaps are config scalars
	// (zero value is the documented degraded mode — the billing/APIKey
	// shape), the gap is `forge:optional-dep`-marked, no App/AppExtras
	// field has the package's Service type, or more than one does
	// (ambiguous — no deterministic canonical instance).
	CanonicalAppField string
	// ConnectPkg is the import alias of the generated Connect package for
	// this service (e.g. "echov1connect") — used by the bootstrap template
	// to reference the `<X>ServiceName` constant when building vanguard
	// REST services. Only populated for services and only when
	// `api.rest: true`; empty for non-services or when REST is off.
	ConnectPkg string
	// ProtoServiceName is the PascalCase proto service identifier (e.g.
	// "EchoService") used to look up the `<ProtoServiceName>Name` constant
	// in the connect-generated package. Combined with ConnectPkg, the
	// bootstrap template emits `<connectPkg>.<ProtoServiceName>Name` as
	// the Connect path passed to vanguard.NewService.
	ProtoServiceName string
}

type BootstrapOperatorData = BootstrapComponentData

type BootstrapPackageData = BootstrapComponentData

type BootstrapServiceData = BootstrapComponentData

type BootstrapTestServiceData struct {
	Name    string // e.g. "api"
	Package string // e.g. "api" (Go package CLAUSE — may differ from the dir name)
	// ImportPath is the handler directory leaf under handlers/ as it exists
	// ON DISK (e.g. "engine_shadow"), resolved by ResolveServiceComponent.
	// The testing.go template builds its import line from this, never from
	// Package — a dir may legally declare a package name that differs from
	// its directory name, and only the directory name belongs in the path.
	ImportPath             string
	FieldName              string // e.g. "API" (exported struct field)
	ProtoServiceName       string // e.g. "ApiService" (proto service name for connect client)
	ProtoConnectImportPath string // e.g. "github.com/foo/bar/gen/services/api/v1/apiv1connect"
	ProtoConnectPkg        string // e.g. "apiv1connect" (Go identifier used at call sites)
	Fallible               bool   // true if New() returns (T, error)
	HasDB                  bool   // true if Deps struct has a DB orm.Context field
	// HasAuthorizer is true when the service's Deps struct declares an
	// `Authorizer` field. The test harness only wires the permissive test
	// authorizer (deps.Authorizer = cfg.authz + the AuthzInterceptor in
	// NewTest<Svc>Server) for services that actually carry that dep. A
	// carve-out / `//forge:external-component` / shared-descriptor-authz
	// service has no Authorizer dep, so emitting deps.Authorizer for it is a
	// compile error — this gate omits it (mirrors inventory_gen's HasAuthorizer
	// and the run-path Mount<Svc>, which only thread the authz interceptor
	// when the service declares the dep). Same signal both halves read: the
	// presence of a Deps field named "Authorizer".
	HasAuthorizer bool
	// Alias mirrors BootstrapComponentData.Alias — when an internal package
	// shares its leaf-name with this service's package, both get role-prefixed
	// aliases ("svcBilling" vs "pkgBilling") so the generated testing.go imports
	// don't collide.
	Alias string
	// VarName is the lowerCamel form of FieldName, used as the testConfig
	// field name (e.g. `c.billingDeps`). Defaults to lowerFirst(Package);
	// becomes "svcBilling" when there's a cross-role collision so the
	// services-range and packages-range testConfig fields stay distinct.
	VarName string
	// AutoStubs lists the per-Deps-field synthesized interface stubs the
	// template should emit and inject as defaults inside NewTest<Svc>.
	// Each entry corresponds to a Deps field whose Go type is an interface
	// declared locally in the handler package (so the testing.go file can
	// reference the interface via the imported handler package alias).
	// Optional-dep fields are excluded — those stay nil to preserve the
	// "graceful dev-mode degrade" semantics. See ParseLocalInterfaces +
	// HasOptionalDepMarker for the detection rules.
	AutoStubs []DepsAutoStub
	// UnresolvedStubs lists Deps fields whose type is a cross-package
	// selector forge couldn't resolve (alias not in imports, package
	// can't load, type isn't an interface). The template emits a
	// `// TODO: stub <type>` line next to NewTest<Svc> so the user
	// sees a visible reminder to hand-roll an override via
	// With<Svc>Deps(...). Empty when every selector resolved cleanly.
	UnresolvedStubs []UnresolvedAutoStub
}

type BootstrapTestingGenInput struct {
	GenContext

	Services           []ServiceDef
	Packages           []BootstrapPackageData
	Workers            []BootstrapWorkerData
	Operators          []BootstrapOperatorData
	MultiTenantEnabled bool
}

type BootstrapWorkerData = BootstrapComponentData

type BuildComponent struct {
	// Name is the runtime kebab name (display / inventory selection only —
	// never a construction key). Used for stable sort + diagnostics.
	Name string
	// FieldName is the exported Go field name on the *Services struct
	// (e.g. "Billing", "SvcBilling"). The collision-aware name shared
	// with the inventory.
	FieldName string
	// VarName is the lower-camel local variable name build.go binds the
	// constructed instance to (e.g. "billing").
	VarName string
	// Alias is the import alias for the component's package.
	Alias string
	// ImportPath is the module-relative import path
	// (e.g. "internal/handlers/billing").
	ImportPath string
	// ServiceTypeKey is the type-identity key this component PRODUCES —
	// the thing a consumer's Deps field type is matched against to draw an
	// edge. It is the FULL IMPORT-PATH-qualified Service interface
	// (e.g. "example.com/proj/internal/billing.Service"), NOT the bare
	// package clause: two packages may share a clause name (a domain
	// `internal/billing` and a handler `internal/handlers/billing` both
	// `package billing`), and keying by clause would collide them, mis-
	// wiring a consumer's domain dep to the handler instance. Import paths
	// are unique, so import-path keying gives each package a distinct
	// identity. Empty for components that expose no collaborator interface
	// (pure leaf workers).
	//
	// The clause-qualified form is retained as a FALLBACK lookup
	// (compPackageKey) for the unambiguous single-clause case + mid-edit
	// projects where the consumer's import block can't be parsed.
	ServiceTypeKey string
	// Deps are the parsed Deps fields, in declaration order.
	Deps []DepsField
	// contains filtered or unexported fields
}

type BuildEdge struct {
	Consumer string // consumer FieldName
	Producer string // producer FieldName
	Field    string // the Deps field on the consumer that carries the dep
	Type     string // the declared field type (for comments / setter stubs)
}

type BuildPlan struct {
	// Order is the topo-sorted construction order (producers first). When
	// a cycle exists, Order contains the acyclic prefix and Cycles names
	// the components that could not be ordered.
	Order []BuildComponent
	// Edges are every resolved consumer->producer collaborator edge,
	// including back-edges that participate in a cycle (see CycleEdges).
	Edges []BuildEdge
	// Cycles lists the FieldNames of components left unordered because
	// they sit on a dependency cycle. Empty for a clean DAG.
	Cycles []string
	// CycleEdges are the specific edges build.go must break with a
	// two-phase setter stub: each is a consumer->producer edge where both
	// endpoints are in Cycles. The user completes the setter after both
	// instances exist.
	CycleEdges []BuildEdge
}

type CRUDMethod struct {
	Method    MethodTemplateData // The RPC
	Entity    EntityDef          // The matched entity
	Operation string             // "create", "get", "list", "update", "delete"
}

type CRUDMethodTemplateData struct {
	MethodName        string // "CreatePatient"
	InputType         string // "CreatePatientRequest"
	OutputType        string // "CreatePatientResponse"
	EntityName        string // "Patient"
	EntityLower       string // "patient"
	Operation         string // "create", "get", "list", "update", "delete"
	AuthRequired      bool
	AuthAction        string // "create", "read", "list", "update", "delete" (middleware constant)
	PkField           string // "Id" (proto PascalCase Go field name)
	PkColumnName      string // "id" (raw DB column name)
	PkGoType          string // "int64"
	HasPkInInput      bool   // true if the request message likely has an ID field
	ResponseField     string // "Patient" — the proto field name in the response that holds the entity
	HasPagination     bool   // true when List method's InputType follows AIP-158 convention
	PaginationStyle   string // "cursor" (default for now)
	HasFilters        bool   // true if list method has filter fields
	FilterFields      []FilterFieldData
	HasOrderBy        bool   // true if list method has order_by field
	HasTenant         bool   // true when the entity has a tenant key field
	TenantGoName      string // e.g., "OrgId", "TenantId" (PascalCase Go field name on entity)
	TenantColumnName  string // e.g., "org_id", "tenant_id"
	UpdateEntityField string // e.g., "Project" — Go field name in the update request that holds the entity
	// UpdateMaskField is the Go field name of the update request's
	// google.protobuf.FieldMask field (e.g. "UpdateMask"). Empty when the
	// request carries no mask — the generated UpdateOp then omits
	// Mask/PersistMasked and pkg/crud keeps the legacy full-replace path.
	// When set, the op wires both hooks so HandleUpdate honors AIP-134:
	// concrete mask paths write only the named columns via
	// db.Update<Entity>Masked.
	UpdateMaskField string
	CreateFields    []CreateFieldData // fields from the create request message
	// ShapeMismatch is true when the request/response message shapes
	// observed in svc.Messages don't line up with what the CRUD body
	// templates assume (AIP-158 page_size/page_token for list, an `id`
	// scalar key for get/update/delete, an entity-typed response field,
	// etc.). That's a legitimate domain decision, not an error — the
	// template emits a tagged stub returning CodeUnimplemented rather
	// than CRUD-body code that wouldn't compile against the real proto,
	// and the user implements the custom shape in the owned shim. See
	// validateCRUDShape for the rules. The stub carries a
	// `forge:custom-read-shape` marker plus MismatchReason so the user
	// (and `forge audit`) can spot it. (Markers emitted before this
	// release spelled it FORGE_CRUD_SHAPE_MISMATCH; audit still
	// recognizes that string for one release.)
	ShapeMismatch  bool
	MismatchReason string
	// CustomFilters are the request fields that DID map to a declared
	// column on the entity (best-effort), used to seed the wired
	// custom-read-shape body's []orm.QueryOption skeleton. Unlike the
	// strict FilterFields (which fail the generate on an unmappable
	// field), these are advisory: fields that don't map to a column are
	// silently skipped so the scaffold always compiles. Only populated
	// when ShapeMismatch is true.
	CustomFilters []FilterFieldData
	// CreateAssigns are the precomputed `e.X = req.X` statements that
	// map create-request fields onto the entity struct (with timestamp/
	// wrapper/array/width conversions baked in).
	CreateAssigns []string
}

type CRUDTemplateData struct {
	Package       string // Go package name, e.g. "patients"
	Module        string // Go module path, e.g. "github.com/demo-project"
	ProtoPackage  string // e.g. "proto/services/patients"
	DBPackagePath string // e.g. "github.com/demo-project/gen/db/v1"
	HasPagination bool   // true if any list method uses pagination
	HasFilters    bool   // true if any list method has filter fields
	HasOrderBy    bool   // true if any list method has order_by
	NeedsORM      bool   // true if pagination, filters, or ordering requires orm import
	HasTenant     bool   // true if any CRUD method operates on a tenant-scoped entity
	// NeedsCRUDLib is true when at least one method emits a real CRUD
	// body (i.e. uses pkg/crud, internal/db, middleware). When every
	// method's request/response shape failed validation and we emit
	// only TODO stubs, the template skips those imports to keep the
	// file compiling.
	NeedsCRUDLib bool
	// NeedsOpsFile is true when the Tier-1 ops file must be written:
	// either NeedsCRUDLib (a real op constructor) OR there is at least
	// one entity conversion pair a wired custom-read-shape body depends
	// on. An all-custom service still needs the conversion helpers, so
	// it gets an ops file carrying only the <entity>ToProto/FromProto
	// pairs (no crud/middleware imports — see the template gating).
	NeedsOpsFile bool
	CRUDMethods  []CRUDMethodTemplateData
	// Entities carries the per-entity proto<->struct conversion pairs
	// (<entity>ToProto / <entity>FromProto) emitted alongside the ops.
	Entities []EntityConvTemplateData
	// NeedsTimestamppb gates the timestamppb import (set when any
	// conversion touches a timestamp column).
	NeedsTimestamppb bool
}

type CRUDTestEntityData struct {
	EntityName       string // "Patient"
	EntityLower      string // "patient"
	PkField          string // "Id"
	PkGoType         string // "int64"
	HasCreate        bool
	HasGet           bool
	HasList          bool
	HasUpdate        bool
	HasDelete        bool
	HasAllCRUD       bool   // true if all 5 operations exist
	HasTenant        bool   // true when the entity has a tenant key field
	TenantGoName     string // e.g., "OrgId"
	TenantColumnName string // e.g., "org_id"
	HasTimestamps    bool   // entity annotation timestamps:true — created_at is asserted set
	// MutableStringField is the Go name of the first non-PK string field
	// (e.g. "Name") — the field the lifecycle test mutates to prove
	// update actually writes. Empty when the entity has none.
	MutableStringField string
	// MutableStringFieldPath is MutableStringField's proto field name
	// (snake_case) — the AIP-134 update_mask path for it.
	MutableStringFieldPath string
	// SecondStringField/-Path name a SECOND mutable string field when the
	// entity has one (skipping the tenant key). The masked-update test
	// loads it with a clobber value the mask does NOT name, then asserts
	// it survived — proving the mask restricts the write. Empty when the
	// entity has only one string field (the non-clobber assertion is then
	// skipped; the masked write itself is still exercised).
	SecondStringField     string
	SecondStringFieldPath string
	CreateMethod          CRUDMethodTemplateData
	GetMethod             CRUDMethodTemplateData
	ListMethod            CRUDMethodTemplateData
	UpdateMethod          CRUDMethodTemplateData
	DeleteMethod          CRUDMethodTemplateData
	Fields                []CRUDTestFieldData // entity proto message fields (minus PK, minus deleted_at)
	CreateFields          []CRUDTestFieldData // fields from the CreateRequest message
	UpdateEntityField     string              // Go field name holding entity in UpdateRequest, e.g. "Project"
}

type CRUDTestFieldData struct {
	ProtoName string    // "Name"
	GoType    string    // "string"
	Kind      FieldKind // scalar, enum, message, wrapper, timestamp, etc.
	TestValue string    // `"test-value"` or `1` or `true`
}

type CRUDTestTemplateData struct {
	Package      string                   // Go package name, e.g. "patients"
	Module       string                   // Go module path, e.g. "github.com/demo-project"
	ProtoPackage string                   // e.g. "proto/services/patients"
	HasTenant    bool                     // true if any entity has tenant isolation
	Entities     []CRUDTestEntityData     // Grouped per-entity test data
	CRUDMethods  []CRUDMethodTemplateData // All CRUD methods (for individual error tests)
	// NeedsFieldMask gates the fieldmaskpb import: true when at least one
	// entity's lifecycle test emits the AIP-134 masked-update block.
	NeedsFieldMask bool
	// TestHelperName mirrors ServiceTemplateData.TestHelperName: the suffix
	// the bootstrap testing generator emits on `app.NewTest<X>` /
	// `app.NewTest<X>Server`. CRUD test scaffolds use this rather than
	// pascal-casing Package so the call site matches the actual factory
	// when an internal package shares the service's leaf name.
	TestHelperName string
}

type CmdCtorRef struct {
	Ctor string // e.g. "NewAuditLogCmd"
}

type CmdGroupItem struct {
	// Module is the project module path (for the import lines).
	Module string

	// Bin is the primary binary name — the cmd/<bin>/cmd import path segment
	// the group file imports for the shared Deps/Serve helpers.
	Bin string

	// Name is the runtime kebab-case component name — the cobra Use value and
	// the <name>.go filename stem. Identical derivation to the app inventory
	// row Name and the typed Mount<Svc> / Worker<X>() / Operator<X>() accessors.
	Name string

	// FieldName is the exported PascalCase suffix used in the generated
	// command constructor (New<FieldName>Cmd) and self-registration. It is
	// the PLAIN per-role name (ToPascalCase of the trimmed service name) —
	// the constructor is a local symbol in the group package, so it is not
	// subject to the cross-role collision rename. Workers/operators set
	// FieldName == MountFieldName (no Components-field mount, no collision).
	FieldName string

	// MountFieldName is the exported suffix of the typed mount METHOD the
	// service command calls: (*app.Components).Mount<MountFieldName>. For
	// services it MUST equal the name inventory_gen emitted — which is
	// collision-aware (ResolveCollisionNaming), so a service whose handler
	// package collides cross-role with an internal package mounts as
	// MountSvc<Pkg>, not Mount<Pkg>. Keeping this SEPARATE from FieldName lets
	// the constructor stay New<Plain>Cmd while the mount call names the
	// collision-renamed Components method — matching inventory_gen exactly and
	// killing the MountBilling/MountSvcBilling mismatch (BUG 1). For
	// workers/operators it is set equal to FieldName (their template doesn't
	// reference a Components mount method).
	MountFieldName string
}

type CmdMainTemplateData struct {
	Module    string
	Bin       string
	Services  []CmdCtorRef
	Workers   []CmdCtorRef
	Operators []CmdCtorRef
}

type CmdServerTemplateData struct {
	Module       string
	ConfigFields map[string]bool

	// AuthProvider is the normalized forge.yaml auth.provider ("jwt",
	// "api_key", "both"; empty when unset/none). Non-empty emits the
	// InstallGeneratedAuth call in runServer.
	AuthProvider string

	// AuthProviderExternal is true for header-carried providers
	// (api_key/both): the generated header-aware interceptor joins the
	// project chain and the authn layer runs in passthrough.
	AuthProviderExternal bool

	// RESTEnabled mirrors forge.yaml `api.rest: true`. When set the cmd
	// composition site builds a vanguard transcoder over the mounted
	// services' Connect paths and serves it in place of the bare mux.
	// Filled by generateCmdServerData from projectAPIRESTEnabled.
	RESTEnabled bool
}

type CmdServiceGroupInput struct {
	Bin      string
	Services []string               // raw service-name spellings
	Packages []BootstrapPackageData // internal packages — for cross-role collision counts
}

type CmdServicesTemplateData struct {
	Skipped []string // runtime names skipped for colliding with built-ins
}

type ConfigBlockRef struct {
	FieldName string // root Config field, e.g. "Trader"
	TypeName  string // generated struct type, e.g. "TraderConfig"
}

type ConfigField struct {
	Name         string // Proto field name (e.g., "database_url")
	GoName       string // Go field name (e.g., "DatabaseUrl")
	GoType       string // Go type (e.g., "string", "int32", "bool")
	ProtoType    string // Proto type (e.g., "string", "int32", "bool")
	EnvVar       string // From config_field.env_var
	Flag         string // From config_field.flag
	DefaultValue string // From config_field.default_value
	Required     bool   // From config_field.required
	Description  string // From config_field.description
	Sensitive    bool   // From config_field.sensitive — projects to a Secret in deploy
	Category     string // From config_field.category — groups fields in deploy gen

	// Role is the (forge.v1.config).role annotation as the bare enum spelling
	// (e.g. "CONFIG_FIELD_ROLE_MODE"; "" for UNSPECIFIED). Config codegen
	// keys semantic behavior (Mode()/DevAuthBypass()) on THIS, never on the
	// field NAME — so renaming a field never changes behavior, and naming a
	// field "environment" without the annotation never auto-enables dev mode.
	// `json:",omitempty"` keeps old descriptors readable (additive contract).
	Role string `json:",omitempty"`

	// MessageType names the referenced config message when this field is
	// a component config-block reference (ProtoType == "message"), e.g. a
	// root `AppConfig` field `TraderConfig trader = 21;` records
	// MessageType "TraderConfig". Empty for scalar fields. Block-reference
	// fields carry no env_var/flag of their own — env binding lives on the
	// referenced message's leaf fields. `json:",omitempty"` keeps old
	// descriptors readable (additive contract, see audit-json skill).
	MessageType string `json:",omitempty"`
}

type ConfigMessage struct {
	Name   string        // Message name (e.g., "AppConfig")
	Fields []ConfigField // Fields with config_field annotations
}

type ConfigTemplateBlockField struct {
	GoName   string // field on Config, e.g. "Trader"
	TypeName string // block struct type, e.g. "TraderConfig"
}

type ConfigTemplateBlockType struct {
	TypeName string
	Fields   []ConfigTemplateField
}

type ConfigTemplateData struct {
	// Fields is every leaf field — root fields plus component config-block
	// leaves — in declaration order, with GoPath set. Drives RegisterFlags
	// and Load so block leaves get the exact same env/flag/default
	// treatment as root fields.
	Fields []ConfigTemplateField
	// RootFields are the leaves declared directly on Config (struct decl).
	RootFields []ConfigTemplateField
	// BlockTypes / BlockFields carry the component config-block shapes:
	// the struct type declarations and the Config fields holding them.
	BlockTypes  []ConfigTemplateBlockType
	BlockFields []ConfigTemplateBlockField
	// RoleModeField is the Go field name of the field tagged
	// role=CONFIG_FIELD_ROLE_MODE, or "" when no field carries it. The
	// generated Mode()/DevAuthBypass() read THIS field — selected by
	// annotation, never by the name "Environment". Renaming the role field
	// is a behavior no-op; naming an unannotated field "environment" never
	// enables dev mode.
	RoleModeField string
	NeedsStrconv  bool

	// Module is the project's Go module path, used by config.go.tmpl to
	// import the generated proto config package (gen/config/v1). Set by
	// GenerateConfigLoader; left empty by callers that only need the
	// field partition (e.g. ConfigBlocksFromMessages).
	Module string
}

type ConfigTemplateField struct {
	GoName         string
	GoType         string
	EnvVar         string
	Flag           string
	DefaultValue   string
	Description    string
	Required       bool
	HasDefault     bool
	DefaultInt32   int32
	DefaultInt64   int64
	DefaultBool    bool
	DefaultFloat32 float32
	DefaultFloat64 float64

	// GoPath is the assignment path on the generated Config struct.
	// Root fields: identical to GoName ("Port"). Component config-block
	// leaves: qualified through the block field ("Trader.MaxPerTick").
	// The Load/flag plumbing in config.go.tmpl assigns via GoPath so one
	// flat loop covers both shapes.
	GoPath string

	// IsDuration marks duration-shaped string fields (see
	// isDurationField). They are emitted as time.Duration on the Config
	// struct and parsed ONCE in Load — consumers never re-parse strings,
	// and a typo'd duration fails startup instead of silently zeroing.
	IsDuration bool

	// StructGoType is the Go type emitted on the Config struct:
	// "time.Duration" for duration fields, GoType for everything else.
	StructGoType string

	// ParseFn names the parse helper Load feeds to loadField for this
	// field ("parseString", "parseInt32", "parsePort", "parseGoDuration",
	// …). Selecting it at generate time keeps the emitted Load a flat
	// list of identical one-liners.
	ParseFn string

	// AllowEmptyEnv preserves the historical string semantics: a string
	// env var explicitly set to "" counts as set. Numeric/bool/duration
	// fields treat an empty env var as unset (parsing "" would always
	// error).
	AllowEmptyEnv bool

	// Role is the (forge.v1.config).role annotation (bare enum spelling, ""
	// for none). Codegen selects semantic fields (e.g. the MODE field) by
	// THIS, never by the field's name.
	Role string

	// Sensitive mirrors (forge.v1.config).sensitive. Sensitive fields get NO
	// CLI flag (defense against shell-history / `ps` leaks) and are resolved
	// from env / Secret mount only — never a flag or an inline default.
	Sensitive bool
}

type CreateFieldData struct {
	ProtoGoName  string    // Go field name on the proto request message, e.g. "Name"
	EntityGoName string    // Go field name on the ORM entity, e.g. "Name"
	Kind         FieldKind // scalar, enum, message, wrapper, timestamp, etc.
	GoType       string    // Go type: "string", "int32", "*timestamppb.Timestamp", etc.
	EnumGoType   string    // For enum fields: the pb.EnumType name
}

type CrossPkgInterfaceResult struct {
	// PackagePath is the import path of the package declaring the
	// interface (e.g. "example.com/proj/internal/repo").
	PackagePath string
	// PackageName is the package's declared Go name (the qualifier
	// the testing.go file should use for the interface, e.g. "repo").
	PackageName string
	// Methods is the flattened method set of the interface, with each
	// method's parameter / result types fully qualified using package
	// aliases that appear in NeededImports.
	Methods []InterfaceMethod
	// NeededImports maps every extra import path the stub's method
	// signatures reference to the local alias used in the rendered
	// signatures. The interface's own package is INCLUDED here so
	// callers can fold one map into the file's import block.
	NeededImports map[string]string
}

type DeployConfigGenInput struct {
	GenContext

	ProjectName string         // forge.yaml `name`
	EnvName     string         // dev / staging / prod / ...
	KCLDir      string         // deploy/kcl (absolute or relative)
	Fields      []ConfigField  // proto-derived config fields (with annotations)
	EnvConfig   map[string]any // per-env config values loaded from the sibling config.<env>.yaml file
}

type Deps struct{}

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

type DepsAutoStub struct {
	// FieldName is the Deps field name as declared (e.g. "Repo").
	FieldName string
	// StubType is the unqualified Go identifier the template should use
	// for the synthesized stub struct (e.g. "stubApiRepo"). Generated
	// from the service alias + field name so two services with the same
	// Deps-field name don't collide at the package level.
	StubType string
	// InterfaceQualified is the package-qualified type expression used
	// when injecting the stub into Deps in NewTest<Svc>.
	//
	// For locally-declared interfaces this carries the literal "<alias>."
	// placeholder so the caller can substitute the post-collision
	// service alias ("svcBilling" vs "billing"). For cross-package
	// interfaces (CrossPackage = true) the prefix is already the
	// declaring package's alias (e.g. "repo.Repository") and must NOT
	// be re-aliased — the service alias is irrelevant to it.
	InterfaceQualified string
	// Methods are the interface's flattened method set rendered for
	// the template's stub-emit loop.
	Methods []InterfaceMethod
	// CrossPackage flags stubs whose interface lives in a package
	// other than the handler's. The caller uses this to skip the
	// "<alias>." rewrite and to fold the stub's ExtraImports into
	// the file's import block.
	CrossPackage bool
	// ExtraImports lists every package the stub's method signatures
	// reference (including the interface's own package). Only populated
	// when CrossPackage = true. The bootstrap_testing assembler
	// deduplicates these across stubs into the top-level
	// ExtraImports field on the template data.
	ExtraImports []ExtraImport
}

type DepsField struct {
	// Name is the exported Go field name as written in the Deps struct,
	// e.g. "Logger", "Config", "Authorizer", "Repo", "Audit", "DB".
	Name string

	// Type is the pretty-printed Go type expression, e.g. "*slog.Logger",
	// "*config.Config", "middleware.Authorizer", "orm.Context", "*sql.DB",
	// "Repository". Used by wire_gen to emit zero-values when no
	// producer matches and to render TODO comments that name the type
	// the user needs to wire.
	Type string

	// Optional is true when the field's doc / inline comment carries
	// the `// forge:optional-dep` marker. Optional fields are
	// intentionally allowed to be nil at construction time:
	//   - validateDeps should NOT enforce them (the user manages
	//     `if s.deps.X != nil { ... }` per RPC as idiomatic Go).
	//   - wire_gen emits the typed zero silently — no TODO comment,
	//     no contribution to the UNRESOLVED header — when no producer
	//     matches.
	// The marker exists because some Deps fields are legitimately
	// optional (rollback-only NATS publisher, optional gateway
	// features, etc.) and the default "must resolve" treatment forces
	// users to either fake-wire them or drop them from validateDeps
	// entirely. Both defeat the design intent.
	Optional bool
}

type EntityColumn struct {
	Name string // column name, snake_case
	// Type is the canonical type: "string", "int64", "float64",
	// "bool", "time", "json", "bytes" (matches schemadef.CanonicalType).
	Type    string
	IsArray bool
	NotNull bool
	IsPK    bool
	// DeclType is the declared SQL type verbatim ("TIMESTAMPTZ").
	DeclType string `json:",omitempty"`
	Default  string `json:",omitempty"`
	// IsGenerated marks GENERATED ALWAYS AS (...) STORED columns — the DB
	// computes them, so the ORM must never write them (Bun's ,scanonly).
	IsGenerated bool `json:",omitempty"`
}

type EntityConvTemplateData struct {
	EntityName       string   // "Item"
	EntityLower      string   // "item"
	ToProtoAssigns   []string // statements: "m.Name = e.Name"
	FromProtoAssigns []string
}

type EntityDef struct {
	Name      string        // "Patient"
	TableName string        // "patients"
	PkField   string        // "id"
	PkGoType  string        // "string"
	Fields    []EntityField // wire-message fields (service proto)
	ProtoFile string        // proto file declaring the wire message
	// Columns is the introspected applied schema for the entity's table.
	Columns []EntityColumn `json:",omitempty"`
	// SearchColumns are the text columns the generated list search
	// filter matches against (convention: every text column).
	SearchColumns    []string `json:",omitempty"`
	SoftDelete       bool     `json:",omitempty"`
	Timestamps       bool     `json:",omitempty"`
	HasTenant        bool     // true when the table has a tenant_id column
	TenantFieldName  string   // proto field name: "tenant_id"
	TenantGoName     string   // Go name: "TenantId"
	TenantColumnName string   // DB column: "tenant_id"
}

type EntityField struct {
	Name      string    // Proto field name: "patient_id"
	GoName    string    // Go name: "PatientId"
	ProtoType string    // "int64", "string", etc.
	GoType    string    // "int64", "string", etc.
	Kind      FieldKind // scalar, enum, message, etc.
	IsFK      bool
	FKTable   string // "patients" (if FK)
	// MessageType carries the fully-qualified message name for
	// message-typed fields (e.g. "google.protobuf.Timestamp"). ProtoType
	// collapses these to "message", which made every timestamp column
	// degrade to TEXT in plan-based migrations/ORM. Additive.
	MessageType string `json:",omitempty"`
}

type EntityPageField struct {
	Name    string // camelCase TS field name: "createdAt"
	Label   string // display label: "Created At"
	IsBadge bool   // render as a status Badge (enum kind or enum-like string name)
}

type ExtraImport struct {
	Path  string
	Alias string
}

type FieldKind string

type FilterFieldData struct {
	ProtoName  string // e.g., "active", "search", "status"
	GoName     string // PascalCase: "Active", "Search", "Status"
	ColumnName string // DB column: "active", "status"
	FieldType  string // "bool", "string", "int32", "int64"
	FilterType string // "exact", "search"
	IsOptional bool   // proto optional keyword
	// SearchColumns is the entity's declared string columns (minus the
	// PK) that a "search" filter spans via orm.WhereILikeAny. A search
	// field never maps to a column of its own — the historical
	// WhereILike("search", ...) hit a phantom column and either errored
	// or (SQLite double-quote fallback) silently matched nothing.
	SearchColumns []string
}

type ForgeDescriptor struct {
	Services []ServiceDef    `json:"services"`
	Configs  []ConfigMessage `json:"configs"`
}

type FrontendHookMethod struct {
	Name       string // PascalCase: "GetUser"
	NameCamel  string // camelCase: "getUser"
	InputType  string // "GetUserRequest"
	OutputType string // "GetUserResponse"
	IsQuery    bool   // true for Get/List/Search, false for mutations
	// EntityScope is the camelCase singular CRUD entity this method
	// operates on ("task" for ListTasks/GetTask/CreateTask), derived
	// from the RPC-name CRUD pattern. Empty for non-CRUD methods.
	// Queries embed it in their query key ([service, entity, method,
	// req]); mutations invalidate the [service, entity] scope when set,
	// falling back to the whole-service scope when empty (a bespoke
	// mutation may touch anything, so over-invalidating is the safe
	// default there).
	EntityScope string
}

type FrontendHookTemplateData struct {
	ServiceName      string // e.g., "UserService"
	ServiceNameCamel string // e.g., "userService"
	ImportPath       string // e.g., "services/users/v1/users_pb" — the service's own proto file
	Methods          []FrontendHookMethod
	// HasQueries / HasMutations let the template conditionally import
	// only the hooks it actually uses. Without these flags the emitted
	// file pulls in useMutation/useQueryClient/UseMutationOptions for
	// query-only services, tripping no-unused-vars in eslint configs.
	HasQueries   bool
	HasMutations bool
	// SchemaImports groups input-message `Schema` value imports by their
	// declaring proto file's TS import path. The template emits one
	// `import { ...Schema }` statement per entry. Same-file schemas land
	// under the service's ImportPath; cross-file schemas land under their
	// own proto file's derived path. Sorted for deterministic output.
	SchemaImports []HookImportGroup
	// TypeImports groups output-message `type` imports the same way.
	// Kept separate from SchemaImports because the template emits these
	// as `import type { ... }` — value vs type-only is required so a
	// `--isolatedModules` build still tree-shakes the type-only side.
	TypeImports []HookImportGroup
	// Workspaces is true when the project opted into the pnpm-workspace
	// layout (frontend.workspaces: true). When true, the rendered hook
	// file lives under packages/hooks/src/generated/ and imports
	// connectClient from "../transport" + proto types from the
	// project's @<scope>/api workspace. When false (the default), the
	// file lives under frontends/<name>/src/hooks/ and imports from the
	// frontend-local @/lib/connect + @/gen paths — byte-identical to
	// projects that predate the workspaces flag.
	Workspaces bool
	// ApiPackage is the workspace package name for the shared API
	// (e.g. "@myapp/api"). Empty when Workspaces is false.
	ApiPackage string
	// EntityScopes is the sorted, deduplicated set of camelCase CRUD
	// entity names ("task", "user") derived from the service's RPC
	// names. The template emits one entity-scope key per entry in the
	// generated query-key factory so mutations can invalidate ONLY the
	// queries for the entity they touched (entity-scoped invalidation)
	// instead of nuking every query on the service.
	EntityScopes []string
}

type GenContext struct {
	// ProjectDir is the project root. Output paths are computed relative
	// to it, and it's the base for the relative paths recorded in
	// Checksums. Some env-scoped emitters tolerate an empty ProjectDir
	// when their output lives outside the project tree (see the emitter's
	// own doc); the core bootstrap emitters require it.
	ProjectDir string

	// ModulePath is the Go module path (e.g.
	// "github.com/acme/control-plane"), used to build import lines and
	// derive resource names (leader-election lease, etc.). Empty for
	// emitters that don't render Go imports (k3d ports, deploy config).
	ModulePath string

	// Checksums, when non-nil, records each rendered Tier-1 file's hash
	// so `forge audit` doesn't flag forge-owned output as stale. A nil
	// tracker is tolerated everywhere — the file is still written.
	Checksums *checksums.FileChecksums
}

type HookImportGroup struct {
	ImportPath string   // e.g., "services/users/v1/users_pb" or "shared/v1/types_pb"
	Symbols    []string // sorted, deduplicated identifiers
}

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

type InfraField struct {
	Name string
	Type string
}

type InjectAssignment struct {
	Field   string
	Expr    string
	Comment string
}

type InjectComponentData struct {
	// FieldName is the exported field on *Services (e.g. "Billing",
	// "SvcBilling") — shared with the inventory and bootstrap naming.
	FieldName string
	// VarName is the lower-camel base name (e.g. "billing"); used for the
	// per-component authz var (`<VarName>Authz`).
	VarName string
	// LocalVar is the local variable Build binds the constructed instance
	// to — VarName + "Inst" so it never shadows the package import alias.
	LocalVar string
	// Alias is the import alias for the component's package.
	Alias string
	// ImportPath is the module-relative import path (e.g.
	// "internal/handlers/billing").
	ImportPath string
	// Package is the Go package clause (for the constructor selector and
	// doc comments).
	Package string
	// Fallible reports whether New returns (T, error). Build wraps the
	// error with the component name when true; assigns directly otherwise.
	Fallible bool
	// NeedsAuthzVar is true when the Deps struct declares an Authorizer
	// field. Build emits a `var authz` block with the dev-bypass swap.
	NeedsAuthzVar bool
	// Assignments are the per-Deps-field key/value pairs, in Deps
	// declaration order, for the New(Deps{...}) literal.
	Assignments []InjectAssignment
}

type InjectGenData struct {
	Module            string
	NeedsAuthorizer   bool
	NeedsConfigImport bool
	// NeedsFmt gates the `fmt` import: it is only referenced in the fallible
	// (New returns error) construction branch, so a project with no fallible
	// component (incl. the zero-component case) must not import it or the
	// generated file fails to compile on an unused import.
	NeedsFmt bool
	// Fields is the Components struct field set (one per component, typed as
	// its concrete handler/worker/operator type), in stable FieldName order.
	Fields []composeField
	// Order is the topo-sorted construction sequence (producers first).
	Order []InjectComponentData
	// HasCycle / CycleEdges drive the two-phase setter stub block.
	HasCycle   bool
	CycleEdges []BuildEdge
}

type InjectGenInput struct {
	GenContext
	Services  []ServiceDef
	Packages  []BootstrapPackageData
	Workers   []BootstrapWorkerData
	Operators []BootstrapOperatorData
}

type Inspector interface {
	DetectFallibleConstructor(dir string) (bool, error)
	DetectDepsDBField(dir string) (bool, error)
}

type InterfaceAssertion struct {
	// DepsField is the Deps field name the pair came from — used only for
	// a deterministic sort + a human-readable comment in the emitted file.
	DepsField string
	// Interface is the qualified interface type string the concrete type
	// satisfies (e.g. "user.Repository", "billing.PlanAssigner").
	Interface string
	// Concrete is the qualified concrete type string assigned to the
	// interface in wire_gen (e.g. "*db.PostgresRepository"). Always a
	// pointer or interface spelling — the matcher only emits assertions
	// for those (see AssignablePairs) so `(Concrete)(nil)` always compiles.
	Concrete string
	// Imports maps package path → package name for every package the two
	// type strings reference. The emitter dedupes across assertions.
	Imports map[string]string
}

type InterfaceMethod struct {
	// Name is the method name as declared (e.g. "GetByID").
	Name string
	// Params is the rendered parameter list including names + types,
	// e.g. "ctx context.Context, id string". Empty when the method
	// takes no parameters.
	Params string
	// Results is the rendered result list with parens when there are
	// multiple, e.g. "(*db.User, error)". Empty when the method
	// returns nothing.
	Results string
	// ReturnStatement is the body of a stub implementation: either
	// "return <zeroes>" or empty when the method returns nothing.
	ReturnStatement string
}

type InventoryGenData struct {
	Module      string
	RESTEnabled bool
	Services    []InventoryServiceData
	// ConnectImports are the *v1connect import lines needed for the
	// ConnectPath descriptor constants (and REST). Deduped + sorted.
	ConnectImports []string
}

type InventoryGenInput struct {
	GenContext
	Services        []ServiceDef
	Packages        []BootstrapPackageData
	Workers         []BootstrapWorkerData
	Operators       []BootstrapOperatorData
	WebhookServices map[string]bool
}

type InventoryServiceData struct {
	// Name is the runtime kebab name — DISPLAY + selection only.
	Name string
	// FieldName is the exported field on *Services holding the instance.
	FieldName string
	// Alias is the import alias for the service's handler package (for the
	// Deps-typed authorizer reference in the Mount closure).
	Alias string
	// ImportPath is the module-relative handler import path.
	ImportPath string
	// Package is the Go package clause.
	Package string
	// ConnectPkg / ProtoServiceName drive the ConnectPath descriptor and,
	// when REST is on, the connect import. Mirrors the bootstrap fields.
	ConnectPkg       string
	ProtoServiceName string
	// BaseService and Version carry the proto identity SPLIT into its
	// version-independent logical name and its proto API version (e.g.
	// proto package "billing.v1" -> BaseService "billing", Version "v1").
	// VERSION-AWARE SEAM (FORGE_SHAPE_REDESIGN — version-aware registry):
	// today identity fuses the version (the v1 rides in ConnectPath/ConnectPkg
	// and the import path), so a future `billing.v2` would register as a
	// SEPARATE service. Recording the version as EXPLICIT METADATA here — a
	// field, not an opaque part of identity — makes v2 an ADDITIVE change
	// later (a second Version on the same BaseService) rather than a breaking
	// redesign. It does NOT change today's behavior: ConnectPath, the mount
	// path, and the field keying are byte-identical for v1 projects; this is
	// pure additive metadata. Version is "" for an unversioned proto package.
	//
	// DEFERRED (NOT in this seam): per-version handler generation /
	// per-version mount adapters. When multi-version lands, the cmd layer
	// will group Inventory rows by BaseService and mount each Version's
	// ConnectPath on its own route; the Mount closure and a per-version
	// Services field are the extension points. Until then a project has at
	// most one Version per BaseService and the grouping is a no-op.
	BaseService string
	Version     string
	// HasWebhooks gates the webhook-route registration in the Mount body.
	HasWebhooks bool
	// HasAuthorizer is true when the service Deps declares an Authorizer —
	// the Mount closure threads its authz interceptor like services_gen.
	HasAuthorizer bool
}

type K3dListener struct {
	GatewayName  string // for de-dup logs and comment lines
	ListenerName string
	Port         int
}

type K3dPortsGenInput struct {
	GenContext

	Listeners []K3dListener // every dev-env listener, in any order
}

type LocalInterface struct {
	// Name is the interface type name as declared (e.g. "Repository").
	Name string
	// Methods enumerates the interface's method set, with embedded
	// interfaces flattened so callers get a single list to walk.
	Methods []InterfaceMethod
}

type MCPGenInput struct {
	GenContext

	ProjectName string       // emitted as the manifest's "project" field; "" tolerated
	Services    []ServiceDef // every parsed Connect service; empty → no-op
}

type MatchKind int

type MessageFieldDef struct {
	Name       string // proto field name: "page_size", "search", "active"
	ProtoType  string // "int32", "string", "bool"
	IsOptional bool   // true if the field has the "optional" label
	// MessageType carries the referenced message's name for message-typed
	// fields (e.g. "Item" for `Item item = 1;`, "google.protobuf.FieldMask"
	// for masks). ProtoType collapses every message field to the literal
	// "message" — which is how the CRUD shape matcher could never match an
	// update request's entity field against the entity name (the false
	// custom-read-shape stub — then spelled FORGE_CRUD_SHAPE_MISMATCH —
	// on forge's own scaffold). Additive:
	// `json:",omitempty"` keeps old descriptors parseable.
	MessageType string `json:",omitempty"`
}

type Method struct {
	Name            string
	InputType       string
	OutputType      string
	ClientStreaming bool
	ServerStreaming bool
	AuthRequired    bool // from (forge.v1.method).auth_required; defaults to true (fail-closed) when unannotated
	// RequiredRoles is the per-method role allow-list. NO proto annotation
	// populates it — forge.v1.MethodOptions has no required_roles field;
	// role policy is code (the user-owned handlers/<svc>/authorizer.go),
	// not proto. The field exists so the authorizer table shape can carry
	// roles if a non-proto source ever supplies them; today it is always
	// empty in parsed descriptors.
	RequiredRoles []string
	// AuthzCustom records (forge.v1.method).authz_custom = true — the method
	// delegates its authorization decision to a hand-written per-service
	// authorizer (a subject/identity/resource-scoped rule not expressible as a
	// role allow-list). Such a method carries NO RequiredRoles (the proto can't
	// express its rule), so a naive role-table emit would write it with EMPTY
	// roles — which on a role table reads as "any authenticated user allowed".
	// The flag lets the authorizer generator emit it FAIL-CLOSED instead, so the
	// generated table can never be misread as an any-authenticated grant. The
	// LIVE decision is enforced by the descriptor-driven RoleInterceptor +
	// the hand-written authorizer.go, not this table.
	AuthzCustom bool
	// Errors records the Connect/gRPC error codes this method may return,
	// derived from (forge.v1.method).errors. Values match connect.Code
	// names (e.g. "NotFound", "PermissionDenied"). Surfaced through
	// generated code so handler authors see the typed error contract at
	// a glance. Informational at runtime — no enforcement (yet).
	Errors []string
	// InputTypeFQ / OutputTypeFQ are the fully-qualified names of the
	// request/response messages (e.g. "shop.v1.CreateOrderRequest",
	// "google.protobuf.Empty"). They key into ServiceDef.Schemas for
	// deep JSON-Schema emission. Empty on descriptors produced by
	// older forge versions — consumers fall back to the short-name
	// InputType/OutputType + Messages map.
	InputTypeFQ  string `json:",omitempty"`
	OutputTypeFQ string `json:",omitempty"`
	// InputProtoFile / OutputProtoFile record the proto file path that
	// physically declares the input/output message. For RPCs whose
	// request/response live in the same proto file as the service these
	// equal ServiceDef.ProtoFile, but they differ when an RPC references
	// a message from another file (e.g. services/users/v1/users.proto's
	// ListUsers returns shared/v1/types.proto's Page). The frontend hooks
	// generator groups imports by these paths so each cross-file message
	// is imported from its declaring _pb.ts file rather than silently
	// referenced as an unresolved identifier.
	InputProtoFile  string
	OutputProtoFile string
}

type MethodTemplateData struct {
	Name            string // RPC method name, e.g. "GetItem"
	InputType       string // proto input message name, e.g. "GetItemRequest"
	OutputType      string // proto output message name, e.g. "GetItemResponse"
	ClientStreaming bool   // true if the client streams requests
	ServerStreaming bool   // true if the server streams responses
	AuthRequired    bool   // true if method_options.auth_required is set
}

type MissingHandlerResult struct {
	NewMethods  []string // names of methods that were generated
	AllUpToDate bool     // true if no new methods were needed
}

type MissingProvider struct {
	// Component is the consuming component's FieldName.
	Component string
	// Field is the Deps field name with no provider.
	Field string
	// Type is the declared field type with no provider.
	Type string
}

type MockEntityTemplateData struct {
	EntityName       string       // "Patient" (PascalCase)
	EntityNamePlural string       // "Patients"
	EntitySlug       string       // "patients" (kebab-case for filename)
	SchemaImport     string       // "PatientSchema"
	TypeImport       string       // "Patient"
	ImportPath       string       // "services/clinic/v1/clinic_pb"
	Fields           []MockField  // fields to populate in mock records
	Records          []MockRecord // 10 mock records
}

type MockField struct {
	Name      string // camelCase TS field name: "orgId"
	ProtoName string // snake_case proto field name: "org_id"
	TSType    string // "string", "number", "boolean"
}

type MockFieldValue struct {
	Name  string // camelCase field name
	Value string // TypeScript literal: `"abc"`, `42`, `true`
	Last  bool   // true if this is the last field (for comma handling in templates)
}

type MockInspector struct {
	contractkit.Recorder
	DetectFallibleConstructorFunc func(string) (bool, error)
	DetectDepsDBFieldFunc         func(string) (bool, error)
}

type MockParser struct {
	contractkit.Recorder
	ParseServicesFromProtosFunc  func(string, string) ([]ServiceDef, error)
	ParseEntityProtosFunc        func(string) ([]EntityDef, error)
	ParseConfigProtoFunc         func(string) ([]ConfigMessage, error)
	ParseConfigProtosFromDirFunc func(string) ([]ConfigMessage, error)
	GetModulePathFunc            func(string) (string, error)
}

type MockRecord struct {
	Fields []MockFieldValue
}

type MockService struct {
	contractkit.Recorder
	GenerateServiceStubFunc         func(ServiceDef, string, ...map[string]bool) error
	RegenerateServiceFileFunc       func(ServiceDef, string) error
	GenerateMissingHandlerStubsFunc func(ServiceDef, string, string, map[string]bool, *checksums.FileChecksums) (*MissingHandlerResult, error)
	GenerateMockFunc                func(ServiceDef, string) (bool, error)
	GenerateAuthorizerFunc          func([]ServiceDef, string, string, map[string]bool, *checksums.FileChecksums) error
	GenerateAuthMiddlewareFunc      func(*config.AuthConfig, string, []string, string, *checksums.FileChecksums) error
	GenerateTenantMiddlewareFunc    func(*config.MultiTenantConfig, string, *checksums.FileChecksums) error
	GenerateCRUDHandlersFunc        func(ServiceDef, []CRUDMethod, string, string, *checksums.FileChecksums) error
	GenerateCRUDTestsFunc           func(ServiceDef, []CRUDMethod, string, string, *checksums.FileChecksums) error
	GenerateCmdServerFunc           func([]ConfigMessage, string, *checksums.FileChecksums) error
	GenerateCmdServerWithFieldsFunc func(map[string]bool, string, string, *checksums.FileChecksums) error
	GenerateConfigLoaderFunc        func([]ConfigMessage, string, *checksums.FileChecksums) error
	GenerateBootstrapTestingFunc    func(BootstrapTestingGenInput) error
	GenerateMigrateFunc             func(string, string, bool, *checksums.FileChecksums) error
}

type MockTransportEntity struct {
	EntityName       string // "Patient"
	EntityNamePlural string // "Patients"
	EntitySlug       string // "patients" (for mock data import path)
	ServiceName      string // "ClinicService" (short, used in display only)
	// ServiceTypeName is the FULLY-QUALIFIED proto service name, e.g.
	// "demo.v1.ClinicService". Connect v2's runtime
	// `method.parent.typeName` returns this form, so the mock transport
	// must build case keys from it (`${ServiceTypeName}/${RPC}`) or the
	// fall-through dispatch silently never matches.
	ServiceTypeName string // "demo.v1.ClinicService"
	ListRPC         string // "ListPatients"
	GetRPC          string // "GetPatient"
	CreateRPC       string // "CreatePatient"
	UpdateRPC       string // "UpdatePatient"
	DeleteRPC       string // "DeletePatient"
	HasList         bool
	HasGet          bool
	HasCreate       bool
	HasUpdate       bool
	HasDelete       bool
	// ItemsField is the camelCase (protojson) name of the list response's
	// repeated field — the key the mock List handler must set on the
	// ListXxxResponse it builds. It mirrors PageTemplateData.ItemsField:
	// the ACTUAL repeated proto field name (e.g. `keys`), not the
	// camelCased entity plural. The mock store variable keeps the plural
	// camelCase identifier; only the response-message KEY uses this.
	ItemsField string
	// PkFieldCamel is the camelCase name of the entity message's
	// PRIMARY-KEY field ("id", "usageEventId", ...). The mutable session
	// store keys records by this field; hardcoding "id" breaks for entities
	// whose PK column isn't literally `id` (e.g. a `usage_event_id` PK
	// projects to a message with no `id` field, failing `tsc`).
	PkFieldCamel string
	// GetEntityFieldCamel / CreateEntityFieldCamel are the camelCase names
	// of the field that wraps the entity on the Get / Create+Update RESPONSE
	// messages. The proto is free to name this field anything
	// (`GetLLMKeyResponse { LLMKey key = 1; }` → `key`, not `lLMKey`), so the
	// mock dispatch must read it off the response descriptor instead of
	// assuming `camelCase(EntityName)` — a wrong key fails `tsc` with "object
	// literal may only specify known properties".
	GetEntityFieldCamel    string
	CreateEntityFieldCamel string
	ImportPath             string // service proto import path for response-schema imports
	// EntityImportPath is the module declaring the ENTITY message schema
	// ("db/v1/patients_pb"). May differ from ImportPath when the entity
	// lives in its own proto file; the mutable-store Create/Update paths
	// need the entity schema to build new records.
	EntityImportPath string
	TypeImport       string // "Patient"
	SchemaImport     string // "PatientSchema"
	// Response/request type names
	ListResponseType   string
	GetResponseType    string
	CreateRequestType  string
	CreateResponseType string
	UpdateRequestType  string
	GetRequestType     string
	DeleteRequestType  string
}

type MockTransportSchemaImportGroup struct {
	ImportPath string   // proto module path, e.g. "services/api/v1/api_pb"
	Symbols    []string // schema symbols imported from this module, dedup'd + sorted
}

type MockTransportTemplateData struct {
	Entities []MockTransportEntity
	// SchemaImportGroups carries the per-ImportPath aggregation of
	// response-schema imports the mock-transport template needs. The
	// template iterates these to emit ONE merged `import { ... } from
	// "@/gen/<path>"` statement per source module, instead of one per
	// entity. Pre-aggregating in Go (vs. with a groupBy template helper)
	// keeps the template loop trivially auditable and lets us preserve
	// entity ordering inside each group.
	SchemaImportGroups []MockTransportSchemaImportGroup
}

type OperatorSpec struct {
	Name string
	Path string
}

type PageField struct {
	Name  string // "title" (camelCase)
	Label string // "Title" (display name)
	Type  string // "text", "number", "checkbox", "date", "textarea"
	// ProtoName is the original snake_case proto field name ("created_at")
	// — the AIP-134 update_mask path for this field.
	ProtoName string
	Required  bool
	ProtoType string // original proto type for reference
	// IsBigInt marks 64-bit integer fields — protobuf-es types them as
	// bigint, so form submissions convert the zod number before mutate().
	IsBigInt bool
	// IsRepeated marks repeated scalar fields (descriptor ProtoType
	// "[]string" etc.). The form renders a comma-separated text input and
	// the submit handler splits it back into the array the RPC expects —
	// without the split, the generated page assigned a string to a
	// string[] request field and failed the TypeScript build.
	IsRepeated bool
	// RepeatedNumeric marks repeated numeric fields whose elements need
	// Number() conversion after the comma split.
	RepeatedNumeric bool
}

type PageTemplateData struct {
	EntityName       string // "Task" (PascalCase)
	EntityNamePlural string // "Tasks"
	EntitySlug       string // "tasks" (kebab-case for URL)
	ServiceName      string // "TaskService"
	ServiceNameCamel string // "taskService"
	HooksImportPath  string // "@/hooks/task-service-hooks"
	TypesImportPath  string // "@/gen/services/tasks/v1/tasks_pb"
	ListRPC          string // "ListTasks" (PascalCase, matching hook name)
	GetRPC           string // "GetTask"
	CreateRPC        string // "CreateTask"
	UpdateRPC        string // "UpdateTask"
	DeleteRPC        string // "DeleteTask"
	HasList          bool
	HasGet           bool
	HasCreate        bool
	HasUpdate        bool
	HasDelete        bool
	// ItemsField is the camelCase (protojson) accessor for the list
	// response's repeated field — the array the list hook's `data` holds.
	// It is the ACTUAL repeated proto field name on the ListXxxResponse
	// message (e.g. `keys` for `ListLLMKeysResponse { repeated LLMKey keys
	// = 1; }`), NOT the camelCased entity plural. They usually coincide
	// ("tasks" for ListTasksResponse.tasks) but diverge whenever the proto
	// names the field differently — and a wrong accessor silently yields
	// `undefined`, breaking the list page, the dashboard count tile, and
	// the mock transport's response shape all at once. Falls back to the
	// camelCased plural for older descriptors that don't carry the field.
	ItemsField   string
	CreateFields []PageField // Fields for the create form
	UpdateFields []PageField // Fields for the edit form
	// UpdateEntityFieldCamel is the camelCase request field wrapping the
	// entity when the update request follows AIP-134 ("task" for
	// `Task task = 1;`). The edit page then nests the form values under
	// it (with the PK inside) instead of spreading them at the top level.
	// Empty for flat update requests (legacy id+fields shape).
	UpdateEntityFieldCamel string
	// UpdateMaskFieldCamel is the camelCase google.protobuf.FieldMask
	// field on the update request ("updateMask"); the edit page sends a
	// mask naming exactly the form's fields so the server's masked write
	// can't clobber columns the form never edits. Empty when the request
	// has no mask.
	UpdateMaskFieldCamel string
	// Response type names for imports
	ListResponseType   string // "ListTasksResponse"
	GetResponseType    string // "GetTaskResponse"
	CreateRequestType  string // "CreateTaskRequest"
	CreateResponseType string // "CreateTaskResponse"
	UpdateRequestType  string // "UpdateTaskRequest"
	GetRequestType     string // "GetTaskRequest"
	DeleteRequestType  string // "DeleteTaskRequest"

	// EntityTypeImportPath is the TS module declaring the entity type
	// ("@/gen/db/v1/tasks_pb"). May differ from TypesImportPath when the
	// entity message lives in its own proto file.
	EntityTypeImportPath string
	// Columns drives the list page's typed column array and the detail
	// page's field rows. Only renderable kinds are included (scalars,
	// enums, timestamps, repeated scalars) — nested messages and maps
	// don't belong in a table cell.
	Columns []EntityPageField
	// SearchFields are the camelCase string-typed fields client-side
	// search filters over. Empty → the list page omits the search box.
	SearchFields []string
	// DisplayField is the camelCase string field used as the human title
	// ("name", then "title"); empty when the entity has neither.
	DisplayField string
	// PkFieldCamel is the camelCase primary-key field ("id").
	PkFieldCamel string
	// HasBadgeColumns reports whether any column renders as a Badge —
	// gates the Badge / enumBadgeVariant imports in page templates.
	HasBadgeColumns bool
	// HasDateCreateFields / HasDateUpdateFields gate the timestamp
	// conversion imports (timestampFromDate / toDatetimeLocal) in the
	// create and edit form templates.
	HasDateCreateFields bool
	HasDateUpdateFields bool
}

type Parser interface {
	ParseServicesFromProtos(dir string, projectDir string) ([]ServiceDef, error)
	ParseEntityProtos(projectDir string) ([]EntityDef, error)
	ParseConfigProto(protoPath string) ([]ConfigMessage, error)
	ParseConfigProtosFromDir(dir string) ([]ConfigMessage, error)
	GetModulePath(dir string) (string, error)
}

type ResolvedComponent struct {
	// Dir is the component's source directory (projectDir/roleRoot/ImportLeaf).
	// Always populated — when FromDisk is false it points at the directory
	// forge WOULD create for a fresh scaffold of this name.
	Dir string

	// ImportLeaf is the directory path relative to the role root, in
	// forward-slash form (e.g. "engine_shadow", "mcp/database"). This is
	// the segment generated import lines must use — it reflects what is
	// actually on disk, not what the naming rules would synthesize.
	ImportLeaf string

	// PackageName is the Go package name. When FromDisk is true it is the
	// package clause parsed from the directory's .go files (which may
	// legally differ from the directory name, e.g. workers/engine_shadow
	// declaring `package engineshadow`). When FromDisk is false it is the
	// synthesized scaffold name.
	PackageName string

	// FromDisk reports whether the directory was found on disk. False
	// means the caller is looking at a component that hasn't been
	// scaffolded yet and PackageName/ImportLeaf are synthesized.
	FromDisk bool
}

type ScenarioRpcData struct {
	Entries     []ScenarioRpcEntry
	TypeImports []HookImportGroup // type-only imports, grouped per declaring module
}

type ScenarioRpcEntry struct {
	Key            string // "demo.v1.TaskService/GetTask" — matches method.parent.typeName dispatch
	RequestType    string // "GetTaskRequest"
	ResponseSchema string // "GetTaskResponseSchema"
}

type SchemaFieldDef struct {
	Name string `json:"name"` // proto field name, snake_case ("page_size")
	// Kind is the proto scalar kind name ("string", "int32", "bool",
	// "bytes", ...) or one of the structured markers "message", "enum",
	// "map".
	Kind string `json:"kind"`
	// TypeName is the fully-qualified message/enum name when Kind is
	// "message" or "enum" (e.g. "shop.v1.Address",
	// "google.protobuf.Timestamp"). Empty for scalars and maps.
	TypeName string `json:"type_name,omitempty"`
	// Repeated marks proto `repeated` fields (JSON arrays). Always
	// false for maps — proto maps are repeated entry messages under
	// the hood, but their JSON encoding is an object, not an array.
	Repeated bool `json:"repeated,omitempty"`
	// Optional is true when the field carries the explicit `optional`
	// label (proto3 field presence). Optional fields stay out of JSON
	// Schema `required` lists.
	Optional bool `json:"optional,omitempty"`
	// Oneof is the containing oneof group's name for members of a
	// real (non-synthetic) oneof. proto3 `optional` fields use a
	// synthetic oneof internally; those report "" here and Optional
	// true instead.
	Oneof string `json:"oneof,omitempty"`
	// Map-typed fields (Kind == "map") record the key/value kinds.
	// MapValueTypeName names the fully-qualified message/enum when the
	// value kind is "message"/"enum".
	MapKeyKind       string `json:"map_key_kind,omitempty"`
	MapValueKind     string `json:"map_value_kind,omitempty"`
	MapValueTypeName string `json:"map_value_type_name,omitempty"`
}

type Service interface {
	// Service-level handler scaffolds.
	GenerateServiceStub(svc ServiceDef, targetDir string, crudMethodNames ...map[string]bool) error
	RegenerateServiceFile(svc ServiceDef, targetDir string) error
	GenerateMissingHandlerStubs(svc ServiceDef, projectDir, targetDir string, crudMethodNames map[string]bool, cs *checksums.FileChecksums) (*MissingHandlerResult, error)
	GenerateMock(svc ServiceDef, mockDir string) (bool, error)

	// Authorization / auth middleware / tenant middleware.
	GenerateAuthorizer(services []ServiceDef, modulePath string, targetDir string, skipDirs map[string]bool, cs *checksums.FileChecksums) error
	GenerateAuthMiddleware(cfg *config.AuthConfig, modulePath string, skipMethods []string, targetDir string, cs *checksums.FileChecksums) error
	GenerateTenantMiddleware(mt *config.MultiTenantConfig, targetDir string, cs *checksums.FileChecksums) error

	// CRUD generation.
	GenerateCRUDHandlers(svc ServiceDef, crudMethods []CRUDMethod, modulePath string, projectDir string, cs *checksums.FileChecksums) error
	GenerateCRUDTests(svc ServiceDef, crudMethods []CRUDMethod, modulePath string, projectDir string, cs *checksums.FileChecksums) error

	// Config loader / cmd-server wiring.
	GenerateCmdServer(messages []ConfigMessage, targetDir string, cs *checksums.FileChecksums) error
	GenerateCmdServerWithFields(configFields map[string]bool, authProvider string, targetDir string, cs *checksums.FileChecksums) error
	GenerateConfigLoader(messages []ConfigMessage, targetDir string, cs *checksums.FileChecksums) error

	// pkg/app bootstrap files.
	GenerateBootstrapTesting(in BootstrapTestingGenInput) error
	GenerateMigrate(targetDir string, modulePath string, hasMigrations bool, cs *checksums.FileChecksums) error
}

type ServiceDef struct {
	Name       string // "EchoService"
	Package    string // "echo.v1"
	GoPackage  string // "github.com/.../gen/proto/echo/v1"
	PkgName    string // "echov1"
	Methods    []Method
	ProtoFile  string
	ModulePath string                       // e.g., "github.com/demo-project"
	Messages   map[string][]MessageFieldDef // message name → fields (e.g., "ListPatientsRequest" → [...])

	// Schemas is the deep type graph for full JSON-Schema emission
	// (MCP manifest): fully-qualified message name → fields, covering
	// every message transitively reachable from any method's input or
	// output type. Well-known types (google.protobuf.*) are NOT
	// included — consumers map those to fixed JSON encodings matching
	// protojson. Empty/nil on descriptors produced by forge versions
	// before this field existed; consumers must fall back to the
	// shallow Messages map in that case. Keyed by fully-qualified name
	// (e.g. "shop.v1.Address") so cross-package short-name collisions
	// can't alias two different messages.
	Schemas map[string][]SchemaFieldDef `json:",omitempty"`

	// SchemaFiles maps a fully-qualified message name (the same keys used
	// in Schemas) to the proto file that physically DECLARES that message.
	// For a message declared in the service's own proto file this equals
	// ProtoFile; for a message pulled in from another file (e.g. a shared
	// `shared.proto` holding the domain entity messages while the CRUD
	// service lives in `services/<svc>/v1/<svc>.proto`) it differs. Codegen
	// that emits a `*Schema` / type import for a message must resolve the
	// import path from the message's DEFINING file, not the service file —
	// otherwise it imports a symbol from a `_pb.ts` module that doesn't
	// export it. Empty/nil on descriptors produced by forge versions before
	// this field existed; consumers must fall back to the service ProtoFile.
	SchemaFiles map[string]string `json:",omitempty"`

	// Enums maps fully-qualified enum name → declared value names, in
	// proto declaration order, for every enum reachable through
	// Schemas. protojson encodes enums as their value-name strings, so
	// this is exactly the "enum" list a JSON Schema needs.
	Enums map[string][]string `json:",omitempty"`
}

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

type ServiceTemplateData struct {
	ServiceName    string // e.g. "EchoService" (or hyphenated CLI form)
	ServicePackage string // Go package CLAUSE, e.g. "echo" (disk-resolved for existing dirs)
	// ServiceImportPath is the internal/handlers/ directory leaf used in scaffolded
	// test imports (`{{.Module}}/internal/handlers/{{.ServiceImportPath}}`). Equals
	// ServicePackage for fresh scaffolds; for EXISTING dirs it is the real
	// directory name, which may legally differ from the package clause.
	ServiceImportPath   string
	Module              string               // e.g. "github.com/demo-project"
	ProtoImportPath     string               // e.g. "proto/services/echo" (without /v1)
	ProtoPackage        string               // same as ProtoImportPath for handlers.go.tmpl
	ProtoConnectPackage string               // e.g. "echov1connect"
	HandlerName         string               // e.g. "EchoService"
	ProtoFileSymbol     string               // e.g. "File_services_echo_v1_echo_proto"
	Methods             []MethodTemplateData // method data for handlers.go.tmpl and test templates
	// TestHelperName is the disambiguated suffix that the bootstrap testing
	// generator uses for `app.NewTest<X>` and `app.NewTest<X>Server` helpers.
	// Equal to PascalCase(ServicePackage) when there's no cross-role
	// collision, else "Svc" + PascalCase(ServicePackage) — matching
	// AssignBootstrapAliases / GenerateBootstrapTesting's collision rule.
	// Test scaffold templates reference this rather than re-pascal-casing
	// ServiceName so the call site stays in sync with the actual factory.
	TestHelperName string
}

type TenantTemplateData struct {
	ClaimField string // JWT claim to extract tenant ID from (e.g. "org_id")
	ColumnName string // DB column name for tenant scoping (e.g. "org_id")
}

type TypeResolver interface {
	// Resolve returns the producing component's FieldName for a Deps
	// field of the given declared type, or "" if none. consumer is the
	// component that DECLARED the field — its import block disambiguates
	// the field's package-clause prefix to a full import path, so two
	// producers sharing a package clause resolve to the correct distinct
	// producer (import-path identity, not bare clause).
	Resolve(consumer BuildComponent, depsType string) string
}

type UnresolvedAutoStub struct {
	// FieldName is the Deps field name as declared.
	FieldName string
	// TypeExpr is the unresolved type expression as written in the
	// Deps struct (e.g. "external.Client").
	TypeExpr string
}

type UnresolvedPlaceholder struct {
	// FieldName is the AppExtras field name.
	FieldName string

	// CurrentType is the type as declared today (typically "any").
	CurrentType string

	// TargetType is the type the user promised to tighten to.
	TargetType string
}

type WorkerSpec struct {
	Name string // user-facing name from forge.yaml (e.g. "climatology_refresh")
	Path string // optional dir path from forge.yaml (e.g. "workers/climatology_refresh"); empty falls back to naming.GoPackage(name)
}