config

type APIConfig struct {
	REST    bool `yaml:"rest,omitempty"`
	OpenAPI bool `yaml:"openapi,omitempty"`

	// ProtoPackage is the proto `package` a SCAFFOLDED service declares
	// (`forge scaffold service`, `forge project new --service`). Either a
	// fixed package every service shares ("controlplane.v1") or a pattern
	// carrying the {service} placeholder, which expands to the snake_case
	// service name ("acme.{service}.v1" → "acme.billing.v1").
	//
	// Absent is the normal case: forge then infers the package from the
	// project's existing service protos (a strict-majority convention) and
	// falls back to "services.{service}.v1" — see
	// generator.ResolveServiceProtoPackage. Set it only to override that
	// inference, e.g. on a project with no services yet. Scaffold-time only:
	// it never rewrites a proto that already exists. go_package is not
	// affected — every service keeps its own gen/services/<svc>/v1 Go
	// package whatever its wire package.
	ProtoPackage string `yaml:"proto_package,omitempty"`
}

type BuildContext struct {
	Path   string
	Source *GitSource
	// SourceDir is the resolved invocation-local directory, never serialized.
	SourceDir string
}

type CIConfig struct {
	Provider    string       `yaml:"provider"`
	Lint        CILintConfig `yaml:"lint,omitempty"`
	Test        CITestConfig `yaml:"test,omitempty"`
	VulnScan    CIVulnConfig `yaml:"vuln_scan,omitempty"`
	E2E         CIE2EConfig  `yaml:"e2e,omitempty"`
	Permissions CIPermConfig `yaml:"permissions,omitempty"`
	// TestSkips tunes `forge ci verify-test-run` — the gate that reads a
	// `go test -json` stream and reports packages that skipped so much
	// their pass proves nothing. Absent (the common case) means the
	// shipped defaults; the block exists so a project can declare the
	// packages whose heavy skipping is legitimate.
	TestSkips CITestSkipsConfig `yaml:"test_skips,omitempty"`
	// Gate extends `forge ci gate` — the local gate behind `task ci` and
	// `task ci:checks` — with the project's own checks.
	Gate CIGateConfig `yaml:"gate,omitempty"`
}

type CIE2EConfig struct {
	Enabled bool   `yaml:"enabled"`           // default false
	Runtime string `yaml:"runtime,omitempty"` // "docker-compose" or "k3d"
}

type CIGateCheck struct {
	// Name is the row in the summary table and the name CI_SKIP and CI_ONLY
	// match. Unique, and not the name of a check forge owns unless this
	// check `replaces` it.
	Name string `yaml:"name"`
	// Command is the argv to run (no shell), from the project root unless
	// Dir is set. Exit 0 is PASS.
	Command []string `yaml:"command"`
	// Dir is the working directory, project-relative.
	Dir string `yaml:"dir,omitempty"`
	// Env is added to the check's environment.
	Env map[string]string `yaml:"env,omitempty"`
	// Requires lists binaries that must be on PATH. A missing one makes the
	// check SKIPPED — which fails the gate unless CI_SKIP names it — rather
	// than a PASS for work that never ran.
	Requires []string `yaml:"requires,omitempty"`
	// Probe is a command that must succeed for the check to run (a docker
	// daemon that answers, a sibling checkout). When it fails the check is
	// SKIPPED with Probe.Reason.
	Probe *CIGateProbe `yaml:"probe,omitempty"`
	// SkipExitCode, when non-zero, is the exit status by which Command says
	// "I could not run here" (77, the automake convention, is the usual
	// choice): the row is SKIPPED with the command's last output line as the
	// reason, instead of FAIL.
	SkipExitCode int `yaml:"skip_exit_code,omitempty"`
	// Lane is the gate lane the check belongs to: checks (the default),
	// test, integration, or a lane of the project's own naming — which only
	// `forge ci gate <lane>` runs, never `all`.
	Lane string `yaml:"lane,omitempty"`
	// Group is a label CI_ONLY can select by (`CI_ONLY=kcl`). Default:
	// "extras".
	Group string `yaml:"group,omitempty"`
	// After names checks this one depends on: it starts once they have
	// finished (whatever their verdict), and selecting it with CI_ONLY
	// selects them too.
	After []string `yaml:"after,omitempty"`
	// Heavy makes the check hold a host-wide heavy slot while it runs, so a
	// shared machine never runs more heavy jobs than it has slots for. Set
	// it for whole-module builds, test runs, renders; leave it off for
	// linters of a few files and network calls.
	Heavy bool `yaml:"heavy,omitempty"`
	// MutatesTree marks a check that writes tracked files (a formatter, a
	// regenerate-and-diff): it runs alone, before every check that only
	// reads the tree, and when it fails on a tree that was clean the gate
	// restores the committed tree.
	MutatesTree bool `yaml:"mutates_tree,omitempty"`
	// Cache, when false, never reuses a cached PASS for this check: set it
	// for a check whose verdict depends on state outside the tree (the
	// network, a sibling checkout, today's advisories). Default true.
	Cache *bool `yaml:"cache,omitempty"`
	// Replaces takes over one of forge's own checks: this check runs in its
	// place, in its lane and position, and forge's command does not run.
	Replaces string `yaml:"replaces,omitempty"`
}

type CIGateConfig struct {
	// Env is set for every check of the gate, forge's and the project's
	// (GOPRIVATE for a private sibling module, a silencing flag).
	Env map[string]string `yaml:"env,omitempty"`
	// Path lists project-relative directories put first on every check's
	// PATH, ahead of forge's pinned tools: a project's own pinned toolchain
	// (`.tools/bin`). `requires` resolves against the same PATH.
	Path []string `yaml:"path,omitempty"`
	// AffectedIgnore lists files no Go test reads, as project-relative globs
	// (`*.md` matches by base name anywhere, `docs/**` a whole tree): a
	// change to one does not force the full unit suite when the gate tests
	// only the packages a branch affects. Any other non-Go change does.
	AffectedIgnore []string `yaml:"affected_ignore,omitempty"`
	// ExtraChecks are the project's own rows. By default each runs in the
	// `checks` lane, so the scaffolded CI job (`task ci:checks`) and a
	// developer's `task ci` run the same ones.
	ExtraChecks []CIGateCheck `yaml:"extra_checks,omitempty"`
}

type CIGateProbe struct {
	Command []string `yaml:"command"`
	// Reason is the SKIPPED note when Command fails.
	Reason string `yaml:"reason,omitempty"`
}

type CILintConfig struct {
	Golangci        bool `yaml:"golangci"`         // default true
	Buf             bool `yaml:"buf"`              // default true
	BufBreaking     bool `yaml:"buf_breaking"`     // default true
	Frontend        bool `yaml:"frontend"`         // default true
	MigrationSafety bool `yaml:"migration_safety"` // default true
}

type CIPermConfig struct {
	Contents string `yaml:"contents,omitempty"` // default "read"
}

type CITestConfig struct {
	Race     bool `yaml:"race"`     // default true
	Coverage bool `yaml:"coverage"` // default false
}

type CITestSkipAllow struct {
	// Package matches the Go import path. Accepted spellings: the full
	// import path, the tail fragment people actually think in
	// ("internal/threads"), or either with a "/..." subtree suffix.
	Package string `yaml:"package"`
	// Reason is why this package legitimately skips. Required.
	Reason string `yaml:"reason"`
	// MaxSkipRatio is the share THIS package may skip. Absent means fully
	// exempt, which is the common case (an integration-only package on a
	// machine with no docker skips 100%, correctly, forever).
	MaxSkipRatio float64 `yaml:"max_skip_ratio,omitempty"`
}

type CITestSkipsConfig struct {
	// MaxSkipRatio is the share of a package's tests that may skip before
	// it is reported. Default 0.5 — "more than half of this package did
	// not run". Range (0,1].
	MaxSkipRatio float64 `yaml:"max_skip_ratio,omitempty"`
	// MinTests is the sample-size floor below which a ratio is arithmetic
	// rather than evidence (1-of-2 is 50% and means nothing). Default 5.
	// It does not apply to a package that skipped EVERY test — "none of
	// them ran" is unambiguous at any size.
	MinTests int `yaml:"min_tests,omitempty"`
	// Allow declares the packages whose heavy skipping is expected, so
	// legitimate skips stop being noise. Each entry REQUIRES a reason.
	Allow []CITestSkipAllow `yaml:"allow,omitempty"`
}

type CIVulnConfig struct {
	Go     bool `yaml:"go"`     // govulncheck, default true
	Docker bool `yaml:"docker"` // trivy, default true
	NPM    bool `yaml:"npm"`    // npm audit, default true

	// Exemptions accepts specific advisory IDs that must not fail the
	// gate. It exists for exactly one situation: a vulnerability with no
	// fixed version, reached only through a code path the project does not
	// execute. Without it the only options are a red gate forever or
	// disabling the scan — and a disabled scan is how the NEXT advisory,
	// the reachable one, goes unnoticed.
	//
	// One list serves both scanners, and each entry's ID says which one it
	// belongs to: govulncheck reports GO-YYYY-NNNN ids, npm audit reports
	// GHSA-xxxx-xxxx-xxxx ids. An id neither scanner reports fails the gate,
	// since it can accept nothing.
	//
	// Scoped by ID on purpose: an exemption suppresses the advisories it
	// names and nothing else, so a new CVE in the very same module or
	// package still fails. See CIVulnExemption for the per-entry contract.
	Exemptions []CIVulnExemption `yaml:"exemptions,omitempty"`
}

type CIVulnExemption struct {
	// ID is the advisory ID exactly as the scanner printed it: a Go
	// advisory ID for govulncheck ("GO-2026-4887"), a GitHub advisory ID
	// for npm audit ("GHSA-vfj7-8cjw-p6xm"). The namespace routes the
	// entry to its scanner.
	ID string `yaml:"id"`
	// Reason states why this advisory cannot affect this project —
	// the unreachability argument, not a ticket number.
	Reason string `yaml:"reason"`
	// Expires is the YYYY-MM-DD date this acceptance stops being
	// honored, forcing a re-review.
	Expires string `yaml:"expires"`
}

type CRDConfig struct {
	// Name is the PascalCase CRD type name. e.g. "Workspace".
	Name string
	// Group is the API group, defaulting to the parent operator's
	// Group. Carried explicitly so a single operator can manage CRDs
	// from multiple groups.
	Group string
	// Version is the API version. Defaults to the parent operator's
	// Version.
	Version string
	// Shape is the reconciler scaffold style. One of
	// "state-machine" (phase-driven), "config" (declarative-only,
	// no state), "composite" (manages sub-resources). Drives which
	// template is rendered for the controller shim.
	Shape string
}

type ComponentConfig struct {
	Name string
	// Kind is THE discriminator: server|worker|cron|operator|binary.
	// See the ComponentKind* constants.
	Kind          string
	Path          string
	Schedule      string // cron expression for kind=cron
	ProtoPackages []string
	// Group is the API group for kind=operator components. e.g.
	// "reliant.dev". Read from the operator package's APIGroup const.
	Group string
	// Version is the API version for kind=operator components. e.g.
	// "v1alpha1". Read from the operator package's APIVersion const.
	Version string
	// CRDs lists the CRDs reconciled by this operator — one per
	// operators/<operator>/<crd-name>_controller.go on disk.
	CRDs []CRDConfig
}

type ConfigGuardConfig struct {
	// EnforceTypedAccess selects the env-access guardrail strictness:
	// "off" | "warn" | "error". Empty resolves to "warn" — use
	// [ConfigGuardConfig.EffectiveEnforceTypedAccess], don't read the raw
	// string. Unknown values are rejected at load time (validate.go).
	EnforceTypedAccess string `yaml:"enforce_typed_access,omitempty"`
	// LoaderPackage is the allowlisted package path that may read the
	// environment directly — the home of forge's generated config loader.
	// Empty resolves to [DefaultLoaderPackage] ("pkg/config"); use
	// [ConfigGuardConfig.EffectiveLoaderPackage].
	LoaderPackage string `yaml:"loader_package,omitempty"`
}

type ConstraintKind string

type ContractsConfig struct {
	Exclude []string `yaml:"exclude"` // packages that opt out
	// InterfaceTypes lists additional cross-package interface types (over
	// and above the built-in list in internal/generator/contract) that the
	// mock generator should treat as mockable — i.e. emit "nil" as the
	// fallback zero value instead of the invalid composite literal "T{}".
	//
	// Entries are matched against the rendered Go type expression of a
	// contract method's return value, e.g. "billing.MeterClient" or
	// "myproject.SomeProjectLocalInterface". Use this when a contract
	// method returns a project-local interface that the mock generator
	// would otherwise mistakenly treat as a struct.
	InterfaceTypes []string `yaml:"interface_types"`
}

type DatabaseConfig struct {
	// Driver is "postgres" or "none" — derived, see DeriveDatabase.
	Driver string `yaml:"-"`
	// MigrationsDir is always db/migrations when there is a database.
	MigrationsDir   string                `yaml:"-"`
	MigrationSafety MigrationSafetyConfig `yaml:"migration_safety,omitempty"`
	// ORM places the generated data layer. Absent, it is internal/db.
	ORM ORMConfig `yaml:"orm,omitempty"`
	// PostgresVersion is the postgres the project runs in production — a
	// major ("16") or an exact release ("16.9.0") — and so the one its
	// tests run against: forge/pkg/pgtest boots its embedded server at this
	// version (and checks an external FORGE_TEST_POSTGRES_URL server's
	// major against it). Empty means pgtest's default, the newest major.
	// Read by pgtest itself from the nearest forge.yaml, so a bare
	// `go test` honours it; FORGE_TEST_POSTGRES_VERSION overrides it for
	// one run.
	PostgresVersion string `yaml:"postgres_version,omitempty"`
}

type DeployConcurrency struct {
	Enabled          bool `yaml:"enabled"`                      // default true
	CancelInProgress bool `yaml:"cancel_in_progress,omitempty"` // default false
}

type DeployConfig struct {
	Environments   []DeployEnvConfig `yaml:"environments,omitempty"`
	Concurrency    DeployConcurrency `yaml:"concurrency,omitempty"`
	FrontendDeploy string            `yaml:"frontend_deploy,omitempty"` // "firebase", "vercel", "none"
	MigrationTest  bool              `yaml:"migration_test,omitempty"`  // test migrations before deploy

	// TargetArch is the GOARCH the deploy target cluster runs on. When
	// unset, forge defaults to amd64 (the predominant k8s host arch).
	// Setting this at the project level means Mac/arm64 dev machines
	// will cross-compile the Go binary (GOOS=linux GOARCH=<target>
	// CGO_ENABLED=0) and pass --platform=linux/<target> to docker
	// buildx so the image kubelet pulls actually runs on the node.
	//
	// Without cross-compile, an arm64-built image deployed onto an
	// amd64 node fails at pod startup with the opaque kernel-level
	// "exec format error". The CLI's --target-arch flag overrides
	// this per-invocation.
	TargetArch string `yaml:"target_arch,omitempty"`
}

type DeployEnvConfig struct {
	Name       string `yaml:"name"`                 // staging, preprod, prod
	Auto       bool   `yaml:"auto,omitempty"`       // auto-deploy
	Protection bool   `yaml:"protection,omitempty"` // environment protection gates
	URL        string `yaml:"url,omitempty"`        // environment URL
}

type Deps struct{}

type DevStackConfig struct {
	// MaxStacks is how many dev stacks may hold a port block at once,
	// counting the default stack (block 0). Zero means unset → the
	// DefaultMaxStacks default, which is what every existing project gets.
	//
	// It bounds NEW allocations only. A registry that already holds a block
	// at or past the ceiling keeps resolving it: a block multiplies into k3d
	// host mappings and into the dev IdP's baked-in `iss` claim and redirect
	// URIs, so lowering this value must never move a port that has already
	// been issued. Reclaiming space is `forge env devstack prune`.
	MaxStacks int `yaml:"max_stacks,omitempty"`

	// BlockSize is the port-number distance between adjacent stacks —
	// stack N's port for base B is B + N*BlockSize. Zero means unset → the
	// DefaultBlockSize default (100), the value this was hardcoded to before
	// it was configurable.
	//
	// It is exposed because it is half of the spacing invariant: two bases
	// that are congruent modulo BlockSize collide at some block, and whether
	// that block is reachable depends on MaxStacks. The
	// forgeconv-allocate-port-spacing lint reads both.
	BlockSize int `yaml:"block_size,omitempty"`
}

type DockerConfig struct {
	// BuildContexts maps a build-context name to anything `docker buildx
	// --build-context name=value` accepts:
	//
	//   - A local filesystem path. Relative paths are resolved against the
	//     project root (the directory holding forge.yaml). The typical
	//     case is a sibling-checkout local replace directive (e.g. a
	//     `replace x => ../x` in go.mod where ../x lives outside the
	//     project's build context).
	//   - A `docker-image://<image>` ref. Passed through verbatim so a
	//     Dockerfile `FROM <name>` can be overridden with a specific image
	//     at build time (local override of a base image during dev,
	//     pin-by-digest in CI, etc.).
	//   - A GitSource mapping (repo, ref, optional subdir). The CLI resolves
	//     it through the shared source cache and explicit local overrides.
	//   - Any other scheme buildkit understands (e.g. `oci-layout://`,
	//     `https://`). Anything containing `://` is passed through
	//     unchanged.
	//
	// Each entry becomes a `--build-context name=value` arg to `docker
	// build`, letting Dockerfiles consume it via `FROM <name>` or
	// `COPY --from=<name>`. Empty when not set; existing projects with no
	// contexts see no change in build behaviour or output.
	BuildContexts map[string]BuildContext `yaml:"build_contexts,omitempty"`
}

type FeatureName = string

type FeaturesConfig struct {
	Codegen       *bool `yaml:"codegen,omitempty"`
	Migrations    *bool `yaml:"migrations,omitempty"`
	CI            *bool `yaml:"ci,omitempty"`
	Build         *bool `yaml:"build,omitempty"`
	Contracts     *bool `yaml:"contracts,omitempty"`
	Frontend      *bool `yaml:"frontend,omitempty"`
	Observability *bool `yaml:"observability,omitempty"`
	HotReload     *bool `yaml:"hot_reload,omitempty"`
	Deploy        *bool `yaml:"deploy,omitempty"`
	Ingress       *bool `yaml:"ingress,omitempty"`
	Operators     *bool `yaml:"operators,omitempty"`
	// contains filtered or unexported fields
}

type FrontendConfig struct {
	Name string
	// Type is "nextjs", "react-native" or "vite-spa" — detected from the
	// framework's own config file, or the KCL declaration's `type`.
	Type string

	// Source pins this frontend's code to another repository at a ref (the
	// KCL `source = forge.GitSource {...}`). nil for an in-repo frontend.
	Source *GitSource
	// Port is the dev-server listen port (KCL `port`). 0 means EPHEMERAL:
	// `forge env up` allocates a free OS port at launch.
	Port int
	// DevRunner is the package manager forge drives the frontend with:
	// "npm", "pnpm" or "yarn". KCL `dev_runner`, else the lockfile on disk.
	DevRunner string
	// BasePath is the URL prefix the frontend is mounted under ("/admin"),
	// "" for the host root. KCL `base_path`, else the literal fallback in the
	// frontend's own next.config.ts. Only meaningful for nextjs.
	BasePath string
	// Output is the Next.js build shape: "standalone", "static" or "server".
	// Read from the frontend's own next.config.ts; "" means standalone.
	Output string
	// Routes restricts which entities this frontend gets generated CRUD pages
	// for (KCL `routes`): route SLUGS ("llm-keys"), an ALLOWLIST. Empty means
	// every CRUD entity. The single value `none` (RoutesNone) means NO
	// generated pages at all. An adopted frontend that declares none gets
	// `none` (frontend_codegen.go).
	Routes []string
	// Adopted reports that forge did not scaffold this frontend — it existed
	// before forge generated into it. generate writes only Tier-1 codegen and
	// the owned seams that code imports into an adopted frontend: no starter
	// components, no CRUD pages, nav or dashboard scaffolds, and no edits to
	// its package.json. Read off disk (frontendScaffoldedByForge); false for
	// a FrontendConfig built in code, which is a frontend forge made.
	Adopted bool
	// Hooks is the package.json `forge.hooks` allowlist: the proto services
	// that get generated React Query hooks in this frontend. nil means every
	// service; an empty list means none. See WantsHooksFor.
	Hooks []string
	// ComponentsDir is the package.json `forge.components_dir`: where forge's
	// component library lives, relative to the frontend directory. "" means
	// DefaultComponentsDir. Read it through ComponentsDirRel.
	ComponentsDir string
	// CodegenProblems are the reasons the frontend's package.json forge block
	// could not be honoured (an unknown key, an escaping components_dir).
	// generate refuses to run while any is present.
	CodegenProblems []string
	// contains filtered or unexported fields
}

type FrontendLintConfig struct {
	CSSHealth      bool   `yaml:"css_health,omitempty"`       // enable stylelint-backed CSS health checks
	NoImportant    string `yaml:"no_important,omitempty"`     // error, warn, off
	NoInlineStyles string `yaml:"no_inline_styles,omitempty"` // error, warn, off
	// Typecheck is the severity of the TypeScript typecheck lane
	// ("error" | "warn" | "off"); see [FrontendLintConfig.EffectiveTypecheck].
	Typecheck string `yaml:"typecheck,omitempty"`
}

type GenerateConfig struct {
	// Hooks are project-declared commands run in declaration order. See
	// [GenerateHook].
	Hooks []GenerateHook `yaml:"hooks,omitempty"`
}

type GenerateHook struct {
	// Name labels the hook in generate's output and in errors. Required and
	// unique.
	Name string `yaml:"name"`
	// Command is the argv to execute: no shell, so no quoting rules differ
	// between platforms. Spell a shell pipeline as [sh, -c, "..."]. A
	// relative command[0] with a path separator resolves against Dir.
	Command []string `yaml:"command"`
	// Dir is the project-relative working directory. Empty is the project
	// root.
	Dir string `yaml:"dir,omitempty"`
	// Writes are the project-relative files or directories the command may
	// write. They are captured into generate's rollback journal before the
	// hook runs, so a failed generate restores them like forge's own output.
	// An undeclared write is not restored; the post-rollback verification
	// names it instead of claiming the tree is back to its pre-run state.
	Writes []string `yaml:"writes,omitempty"`
}

type GitSource struct {
	// Repo is the repository: host/owner/name
	// ("github.com/reliant-labs/reliant"), which forge expands to an https
	// clone URL, or an explicit https://, ssh://, or git@host:owner/name
	// URL, which is used verbatim.
	Repo string `yaml:"repo" json:"repo"`
	// Ref is the tag, branch, or commit sha to check out. Required —
	// forge does not default to a repository's default branch, because an
	// unpinned dependency is precisely the problem this type solves.
	Ref string `yaml:"ref" json:"ref"`
	// Subdir is the path within the repository holding this component's
	// source ("web"). Empty means the repository root.
	Subdir string `yaml:"subdir,omitempty" json:"subdir,omitempty"`
}

type K8sConfig struct {
	KCLDir string `yaml:"kcl_dir"`
}

type KCLFrontend struct {
	Name string
	Type string
	// Path is the frontend's directory as the KCL declared it, relative
	// to the project root (or absolute). Empty means the KCL named no
	// path, in which case the frontends/<name> convention applies.
	Path string
	// HasSource reports whether the declaration pins its code to another
	// repository. Such a frontend has no directory in this tree by
	// design, so it is never a codegen target here.
	HasSource bool
	// Port, DevRunner and BasePath are the declaration's dev-server port,
	// package manager and mount prefix; zero/empty means it declared none.
	Port      int
	DevRunner string
	BasePath  string
	// Routes is the CRUD-page allowlist (forge.Frontend.routes); empty means
	// every CRUD entity, ["none"] means no generated pages.
	Routes []string
}

type LintConfig struct {
	Frontend FrontendLintConfig `yaml:"frontend,omitempty"`
	// HandlerFileMaxLOC is the per-file LOC threshold above which the
	// forgeconv-handler-file-size analyzer warns. Counts non-blank, non-
	// comment Go source lines under handlers/<svc>/*.go. A value of 0 (or
	// the field unset) is treated as the built-in default — see
	// [LintConfig.EffectiveHandlerFileMaxLOC] for the canonical value.
	HandlerFileMaxLOC int `yaml:"handler_file_max_loc,omitempty"`

	// Rules is the repo-wide severity dial for forge-owned lint rules:
	// rule ID → "off" | "warn" | "error". It is the COARSEST of the
	// three suppression levels (see internal/linter/suppress) and the
	// one to reach for last, because — like a path glob in
	// .golangci.yml — it silently swallows every future finding for
	// that rule, including the one you would have wanted to see.
	//
	// Prefer a file or line directive when the exemption is local. This
	// map is for rules that genuinely do not apply to the whole project
	// (a CLI has no handlers; an operator has no frontend), where the
	// alternative is annotating every file.
	//
	// The `warn` setting is the load-bearing one: it lets a project
	// adopt a newly-added opinionated rule incrementally instead of
	// choosing between "fails the build today" and "off".
	//
	// Only forge's OWN rules are addressable here. golangci-lint,
	// eslint, stylelint and buf each have their own config file and
	// their own suppression syntax, and forge deliberately does not
	// proxy them — a second place to configure the same linter is a
	// place for the two to disagree.
	//
	// The special key "*" applies to every forge rule; an exact rule ID
	// beats it.
	Rules map[string]string `yaml:"rules,omitempty"`

	// Tracing configures the tracing lane (`forge lint --tracing`).
	Tracing TracingLintConfig `yaml:"tracing,omitempty"`

	// AllowSkip accepts, by name and with a reason, a gating lane that
	// could NOT run. Such a lane fails `forge lint` by default — a check
	// that did not run is not a check that passed — so this is the
	// project-level opt-out, the forge.yaml twin of `forge lint
	// --allow-skip`. An accepted lane is still listed as SKIPPED (allowed)
	// in the verdict, with its reason. It accepts only "could not run": a
	// lane that ran and found problems still fails.
	AllowSkip []LintSkipAllowance `yaml:"allow_skip,omitempty"`
}

type LintSkipAllowance struct {
	// Lane is the lane's name as the verdict prints it ("frontend lint")
	// or its flag spelling ("frontend-lint").
	Lane string `yaml:"lane"`
	// Reason says why the lane may not run here. Required.
	Reason string `yaml:"reason"`
}

type LogWrapperConfig struct {
	// Call is the helper, as "<import path>.<Func>":
	// github.com/acme/app/internal/logging.Info.
	Call string `yaml:"call"`
	// ContextCall is what a call is rewritten to, as "<import path>.<Func>",
	// taking the context first and then the helper's arguments unchanged
	// (log/slog.InfoContext). Empty means "<Call>Context" in the helper's
	// own package.
	ContextCall string `yaml:"context_call,omitempty"`
}

type MigrationSafetyConfig struct {
	Enabled           *bool  `yaml:"enabled,omitempty"`            // nil = enabled
	UnsafeAddColumn   string `yaml:"unsafe_add_column,omitempty"`  // error, warn, off
	DestructiveChange string `yaml:"destructive_change,omitempty"` // error, warn, off
	VolatileDefault   string `yaml:"volatile_default,omitempty"`   // warn, error, off
	// RequireCompatDeclaration makes `forge lint --migration-safety` require
	// every migration after the baseline to declare `-- forge:backward-compatible
	// — <why>` or `-- forge:breaks-rollback <why>` (migration-compat-undeclared,
	// migration-compat-reason). Off by default.
	RequireCompatDeclaration bool `yaml:"require_compat_declaration,omitempty"`
}

type ORMConfig struct {
	// Package is the project-relative directory the ORM projects into —
	// every <entity>_orm_gen.go, store_gen.go and _repo_ext.go seam — and
	// so the Go package they declare (its last path element). Empty means
	// DefaultORMPackage.
	//
	// It exists for a project that already has a data layer of its own in
	// internal/db: there the projection's names (Chat, Message, Store,
	// NewStore) collide with the project's, one package cannot declare
	// both, and porting onto the store one table at a time needs the two
	// to live side by side. `package: internal/store` puts the projection
	// in its own package; every generated consumer (CRUD wiring, the store
	// Deps in compose.go, factories, shapes, the drift guard) follows it.
	Package string `yaml:"package,omitempty"`
}

type ObservabilityConfig struct {
	// LogLevel is the slog level at which the LogMiddleware records
	// SUCCESSFUL component calls ("debug" | "info" | "warn" | "error").
	// Every success is recorded unless the seam appends
	// observe.WithSuccessSampling to LogMiddleware, which samples them per
	// method. Failures always log at Error regardless. Default "debug"
	// keeps success logging quiet under a production Info handler. An
	// unknown value falls back to the default.
	LogLevel string `yaml:"log_level,omitempty"`
}

type PlanEntity struct {
	Name       string `yaml:"name" json:"name"`                                 // PascalCase message name, e.g. "Project"
	TableName  string `yaml:"table_name,omitempty" json:"table_name,omitempty"` // override; defaults to pluralized snake_case
	SoftDelete bool   `yaml:"soft_delete,omitempty" json:"soft_delete,omitempty"`
	Timestamps bool   `yaml:"timestamps,omitempty" json:"timestamps,omitempty"`
	// AppendOnly marks an immutable ledger: the table is declared
	// `forge:append-only` in its COMMENT ON TABLE, so the generated store
	// omits Update/UpdateMasked/Delete entirely. The declaration lives in
	// the MIGRATION (schemadef.TableMarkerAppendOnly) — the proto marker of
	// the same name is a birth-time instruction that nothing carries
	// forward, which is why the store used to expose mutators for a table
	// postgres rejects every write to.
	AppendOnly bool              `yaml:"append_only,omitempty" json:"append_only,omitempty"`
	Fields     []PlanEntityField `yaml:"fields" json:"fields"`
	// Constraints are the table's named UNIQUE / CHECK / FOREIGN KEY
	// constraints, which the ORM generator publishes as per-entity
	// constants so a service can branch on orm.ConstraintName(err) without
	// hardcoding the identifier. The PRIMARY KEY is deliberately absent:
	// inserting a duplicate id is a forge-internal concern (pkg/crud
	// generates the ULID), so no service branches on it, and emitting a
	// constant nobody reads is noise in every generated file.
	Constraints []PlanEntityConstraint `yaml:"constraints,omitempty" json:"constraints,omitempty"`
	// ReadOnly marks a view entity (codegen.EntityDef.ReadOnly): the store
	// emits List/Count and Get by its key, and no Create/Update/Delete.
	ReadOnly bool `yaml:"read_only,omitempty" json:"read_only,omitempty"`
}

type PlanEntityConstraint struct {
	Name string         `yaml:"name" json:"name"`
	Kind ConstraintKind `yaml:"kind" json:"kind"`
	// Columns are the columns the constraint spans, in key order. It is
	// what makes the generated doc comment say WHICH columns must be
	// distinct rather than just naming the constraint back to the reader.
	Columns []string `yaml:"columns,omitempty" json:"columns,omitempty"`
}

type PlanEntityField struct {
	Name       string `yaml:"name" json:"name"` // snake_case proto field name
	Type       string `yaml:"type" json:"type"` // "string", "int64", "bool", "google.protobuf.Timestamp"
	PrimaryKey bool   `yaml:"primary_key,omitempty" json:"primary_key,omitempty"`
	NotNull    bool   `yaml:"not_null,omitempty" json:"not_null,omitempty"`
	Unique     bool   `yaml:"unique,omitempty" json:"unique,omitempty"`
	Default    string `yaml:"default,omitempty" json:"default,omitempty"`
	References string `yaml:"references,omitempty" json:"references,omitempty"` // "users.id"
	// Generated marks a GENERATED ALWAYS AS (...) STORED column: the DB
	// computes it, so the ORM emits ,scanonly (never written on
	// INSERT/UPDATE).
	Generated bool `yaml:"generated,omitempty" json:"generated,omitempty"`
	// Identity marks a GENERATED ... AS IDENTITY column. Postgres reports no
	// DEFAULT for one, so with Default it is what says the database
	// allocates a key (the ORM's ,autoincrement) — never the key's type.
	Identity bool `yaml:"identity,omitempty" json:"identity,omitempty"`
	// Secret marks a column backed by a `// forge:secret` wire field: the
	// read path never packs it (a client always reads it back as ""), so the
	// generated repo's Spec.SecretColumns preserves it on a maskless
	// full-replace Update rather than clobbering the stored value with "".
	Secret bool `yaml:"secret,omitempty" json:"secret,omitempty"`
	// Immutable marks a column declared `forge:immutable` in a COMMENT ON
	// COLUMN. It projects to Bun's `skipupdate` tag option, so a full-replace
	// UPDATE omits it from the SET clause while an explicit update_mask
	// naming it still writes it.
	//
	// The declaration lives in the MIGRATION, not the proto: whether a column
	// may be rewritten is a fact about storage, and the wire contract and the
	// schema evolve on independent clocks. Inferring it from the absence of a
	// wire field is wrong — a column can be absent from the API and still be
	// ordinary mutable state (an internal score, a denormalized cache).
	Immutable bool `yaml:"immutable,omitempty" json:"immutable,omitempty"`
	// Version marks a column declared `forge:version` in a COMMENT ON
	// COLUMN. It opts the entity into optimistic concurrency control:
	// forge/pkg/crud's Repo adds it to Update/UpdateMasked's WHERE clause
	// (matched against the caller's last-read value) and increments it on
	// a successful write, failing a lost race with svcerr.ErrAborted
	// rather than silently overwriting a concurrent writer's change.
	Version bool `yaml:"version,omitempty" json:"version,omitempty"`
	// FillStrategy carries a `forge:fill=<strategy>` COMMENT ON COLUMN
	// declaration verbatim ("ulid" or "handler"), "" for none. "ulid" makes
	// forge/pkg/crud's Repo generate one at Create for this (non-PK) column,
	// the same chokepoint that already ULID-generates an empty string PK.
	// "handler" changes no codegen behavior — it only suppresses the
	// unsatisfiable-column lint. See schemadef.ColumnMarkerFill.
	FillStrategy string `yaml:"fill_strategy,omitempty" json:"fill_strategy,omitempty"`
	// GoType carries a `forge:go-type=<spec>` COMMENT ON COLUMN declaration
	// verbatim (codegen.ParseGoTypeOverride): the struct field's Go type in
	// place of the projected one. "" for none.
	GoType string `yaml:"go_type,omitempty" json:"go_type,omitempty"`

	// ZeroRejected marks a column a CHECK keeps from holding its Go zero
	// (codegen.EntityColumn.ZeroRejected): its zero is "unset", so a DEFAULT
	// applies through ,nullzero rather than a pointer field.
	ZeroRejected bool `yaml:"zero_rejected,omitempty" json:"zero_rejected,omitempty"`
}

type PlanField struct {
	Name string `yaml:"name" json:"name"`
	Type string `yaml:"type" json:"type"`
}

type PlanFile struct {
	ProjectName string         `yaml:"project_name"`
	GoModule    string         `yaml:"go_module"`
	GoVersion   string         `yaml:"go_version,omitempty"`
	MockData    bool           `yaml:"mock_data,omitempty"`
	Services    []PlanService  `yaml:"services,omitempty"`
	Packages    []PlanPackage  `yaml:"packages,omitempty"`
	Frontends   []PlanFrontend `yaml:"frontends,omitempty"`
	Entities    []PlanEntity   `yaml:"entities,omitempty" json:"entities,omitempty"`
}

type PlanFrontend struct {
	Name string `yaml:"name"`
	Kind string `yaml:"kind,omitempty"` // "mobile" for React Native; empty/default = Next.js web
}

type PlanPackage struct {
	Name        string `yaml:"name"`
	Kind        string `yaml:"kind,omitempty"` // "eventbus", "client", or empty
	Description string `yaml:"description,omitempty"`
}

type PlanRPC struct {
	Name        string      `yaml:"name" json:"name"`
	Description string      `yaml:"description,omitempty" json:"description,omitempty"`
	Request     []PlanField `yaml:"request,omitempty" json:"request,omitempty"`
	Response    []PlanField `yaml:"response,omitempty" json:"response,omitempty"`
}

type PlanService struct {
	Name        string    `yaml:"name" json:"name"`
	Description string    `yaml:"description,omitempty" json:"description,omitempty"`
	RPCs        []PlanRPC `yaml:"rpcs,omitempty" json:"rpcs,omitempty"`
}

type ProjectConfig struct {
	Name       string `yaml:"name"`
	ModulePath string `yaml:"module_path,omitempty"`
	// Kind is the project shape (service|cli|library). It is not a forge.yaml
	// field: the loader DERIVES it from the project's real sources — the KCL
	// deploy tree, the pkg/app composition root, internal/handlers/, the
	// service protos, and cmd/<name>/main.go (see deriveProjectKindFromSources).
	// The yaml tag is "-" so a stale `kind:` in forge.yaml is reported with a
	// migration hint instead of being honored.
	Kind   string `yaml:"-"`
	Binary string `yaml:"binary,omitempty"` // "per-service" (default), "shared" — one Go binary, cobra subcommand per service
	// ForgeVersion records the forge binary version that this project's
	// generated artifacts were last produced against. It is set at
	// `forge project new` time, bumped after a successful `forge project upgrade`, and
	// consulted by `forge generate` to warn when the forge binary on
	// PATH has drifted from the version pinned by the project. Empty
	// (legacy) projects are treated as "0.0.0".
	ForgeVersion string `yaml:"forge_version,omitempty"`
	// Harness records which AI harness this project was scaffolded for
	// (`forge project new --harness`). It is the ONLY durable record of that
	// choice: the flag is read once at scaffold time, and without it on disk
	// every later `forge generate` has to guess. It selects the harness
	// pointer files (CLAUDE.md, .cursorrules, ...) written beside AGENTS.md,
	// which every harness gets. Forge never writes skill bodies for any
	// harness. Empty means reliant.
	Harness string `yaml:"harness,omitempty"`
	// NOTE: there is intentionally NO project-level `hot_reload:` field.
	// The single hot-reload switch is `features.hot_reload`, which the dev
	// loop and the air-config codegen actually read; a second top-level key
	// spelled the same way resolved through a different accessor that no
	// caller ever invoked. A `hot_reload:` key at the top level is reported
	// with a migration hint (see removedSchemaKeys).
	//
	// NOTE: there is intentionally NO `components:` field, in yaml or in
	// memory. What a project builds and runs — Connect servers, workers,
	// crons, operators, secondary binaries — is declared by the code itself
	// (the proto descriptor, internal/workers/, internal/operators/, cmd/),
	// and a config object carrying a copy would be a second source of truth
	// that is empty exactly when nobody remembered to fill it. A caller that
	// needs the component inventory asks the project for it:
	// codegen.DiscoverProjectComponents. A `components:` key in forge.yaml is
	// reported with a migration hint (see removedSchemaKeys).
	//
	// NOTE: there is intentionally NO `packages:` field either. An internal
	// package is declared by internal/<name>/contract.go — the file the
	// bootstrap/injector codegen has always walked for — and its
	// outbound-boundary claim by the `//forge:outbound-io` marker in its own
	// source. The retired list was never a codegen input: deleting it left
	// every package still imported, constructed and middleware-wrapped in
	// internal/app/compose.go. It steered only the REPORTERS, so a stale
	// entry made `forge project map` / `forge project audit` / the
	// architecture doc name a package that does not exist while hiding one
	// that does. They now resolve through codegen.DiscoverInternalPackages.
	// A `packages:` key is reported with a migration hint (see
	// removedSchemaKeys).
	// Frontends is the frontend inventory. It is DERIVED, never read from
	// forge.yaml (there is no `frontends:` key): the loader fills it from the
	// frontends found on disk, and `forge generate` overlays the KCL
	// `forge.Frontend` declarations onto it. See frontend_inventory.go.
	Frontends []FrontendConfig `yaml:"-"`

	// The section blocks below are all omitempty: a freshly scaffolded
	// forge.yaml leaves them absent and the loader fills shape-derived
	// defaults (see ApplyDerivedDefaults in derive.go). A present block
	// is taken literally — write the block (or a single key) to override.
	Database DatabaseConfig `yaml:"database,omitempty"`
	CI       CIConfig       `yaml:"ci,omitempty"`
	// NOTE: there is intentionally NO `build:` field. Build is declared
	// per-service, per-env in KCL (the polymorphic Build union —
	// GoBuild | DockerBuild | ShellBuild on each forge.Service); forge.yaml
	// carries zero build config. A `build:` key in forge.yaml is REJECTED
	// as an unknown key by the strict loader (walkUnknownKeys) rather than
	// silently ignored — version stamping moves to a KCL GoBuild.ldflags
	// `-X` entry.
	Deploy    DeployConfig    `yaml:"deploy,omitempty"`
	Docker    DockerConfig    `yaml:"docker,omitempty"`
	K8s       K8sConfig       `yaml:"k8s,omitempty"`
	Lint      LintConfig      `yaml:"lint,omitempty"`
	Contracts ContractsConfig `yaml:"contracts,omitempty"`
	// Config steers humans and LLMs away from reading the environment
	// directly (os.Getenv / os.LookupEnv / os.Environ) and toward forge's
	// generated, dependency-injected typed config object. See
	// [ConfigGuardConfig] for the enforce_typed_access / loader_package
	// semantics and the absent-key default (warn).
	Config ConfigGuardConfig `yaml:"config,omitempty"`
	// NOTE: there is intentionally NO `auth:` block. Authentication is owned
	// code — internal/app/auth.go's SetupAuth picks the validator, and
	// issuer/audience/JWKS are per-deployment values that live in env vars
	// routed through KCL. An `auth:` key is reported with a migration hint
	// (see removedSchemaKeys).
	// Features is DERIVED from what exists in the repo (see
	// DeriveFeatureDefaults). The optional `features:` block pins a feature
	// on or off whatever the tree says — the switch for a project whose
	// shape implies a feature it does not want (see FeaturesConfig).
	Features FeaturesConfig `yaml:"features,omitempty"`
	// Observability seeds the OWNED per-package observe_chain.go seam that a
	// generated component decorator routes through. The values are read at
	// `forge scaffold` time to stamp the initial chain (log level, etc.);
	// the seam is user-owned thereafter. See [ObservabilityConfig].
	Observability ObservabilityConfig `yaml:"observability,omitempty"`
	// API toggles project-level API protocol skins layered on top of the
	// Connect mux. Default zero-value leaves both REST and OpenAPI off so
	// existing projects regenerate identically. See [APIConfig] for the
	// per-field semantics.
	API APIConfig `yaml:"api,omitempty"`
	// DevStack bounds forge's parallel-dev-stack port allocation — how many
	// stacks can run side by side, and how far apart their port blocks sit.
	// See [DevStackConfig] for why this has to be declared rather than
	// inferred.
	DevStack DevStackConfig `yaml:"dev_stack,omitempty"`
	// Generate declares commands `forge generate` runs for the project —
	// the escape hatch for a generator forge does not own. See
	// [GenerateConfig] / [GenerateHook]; read by the "generate hooks
	// (forge.yaml)" pipeline step.
	Generate GenerateConfig `yaml:"generate,omitempty"`
	// Upgrade declares what `forge project upgrade` does beyond forge's own
	// codemods and playbooks: today, how to re-vendor a contract copied from
	// another repository. See [UpgradeConfig]; read by upgrade_converge.go.
	Upgrade UpgradeConfig `yaml:"upgrade,omitempty"`
	// contains filtered or unexported fields
}

type Service interface {
	// EffectiveKind normalizes a raw kind string to one of the canonical
	// ProjectKind* constants, defaulting to "service" for empty/unknown input.
	EffectiveKind(kind string) string
}

type TracingLintConfig struct {
	// LogWrappers names the project's own context-free logging helpers —
	// a `logging.Info(msg, args...)` that calls slog.Info — so
	// forge-tracing-log-without-ctx flags and rewrites their calls the way
	// it does slog's own.
	LogWrappers []LogWrapperConfig `yaml:"log_wrappers,omitempty"`
}

type UpgradeConfig struct {
	// VendoredContracts declare contracts the project vendors from another
	// repository, and how to catch the vendored copy up. See
	// [VendoredContract].
	VendoredContracts []VendoredContract `yaml:"vendored_contracts,omitempty"`
}

type ValidationError struct {
	Path   string
	Issues []validationIssue
}

type VendoredContract struct {
	// Name labels the contract in upgrade's output. Required and unique.
	Name string `yaml:"name"`
	// Report is the project-relative path of the lag report the project's own
	// check writes.
	Report string `yaml:"report"`
	// Schema is the report's expected `schema` value. A report claiming
	// another is not trusted.
	Schema string `yaml:"schema"`
	// EnvPath is a dotted path to an object in the report whose string values
	// become environment variables for the commands (for example
	// "revendor.env").
	EnvPath string `yaml:"env_path,omitempty"`
	// Commands are the argv lists that re-vendor, run in order from the
	// project root. No shell: spell a pipeline as [sh, -c, "..."].
	Commands [][]string `yaml:"commands"`
}