builder.go

package main

import (
	"bytes"
	"context"
	"crypto/sha256"
	"embed"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io/fs"
	"net"
	"os"
	"path/filepath"
	"slices"
	"strconv"
	"strings"
	"text/template"

	"github.com/codefly-dev/core/agents/communicate"
	dockerhelpers "github.com/codefly-dev/core/agents/helpers/docker"
	"github.com/codefly-dev/core/agents/services/sbom"
	v0 "github.com/codefly-dev/core/generated/go/codefly/base/v0"
	"github.com/codefly-dev/core/resources"
	"github.com/codefly-dev/core/standards"
	"github.com/codefly-dev/core/wool"

	"github.com/codefly-dev/core/agents/services"
	"github.com/codefly-dev/core/agents/services/upgrade"
	builderv0 "github.com/codefly-dev/core/generated/go/codefly/services/builder/v0"
	"github.com/codefly-dev/core/shared"
	"gopkg.in/yaml.v3"
)

const (
	// bootstrapDirectory is the agent-owned staging root written into the build
	// context. It carries the generated bootstrap program, the plan identity, and
	// one immutable copy of every packaged migration source.
	bootstrapDirectory = "bootstrap"
	// stagedChecksumFile is the sha256sum manifest the bootstrap program verifies
	// before it applies anything.
	stagedChecksumFile = "sources.sha256"
	// bootstrapMarkerFile doubles as the staged tree's git ignore rule: the
	// directory is regenerated on every build, so it must never be committed,
	// and existing services get that for free without editing their own
	// .gitignore.
	bootstrapMarkerFile = ".gitignore"
	// bootstrapMarker identifies a bootstrap directory this agent generated and
	// may therefore replace.
	bootstrapMarker = "# codefly-generated postgres bootstrap"
	// runtimeAccessFile is rendered at the build context root, beside the staged
	// bootstrap tree, because the Dockerfile COPYs it root-relative.
	runtimeAccessFile = "runtime-access.sql"
	// bootstrapIgnoreFile keeps the build context down to what the image
	// actually copies. The context is the whole service directory, which carries
	// local configuration and secrets, and a context is transferred to the
	// daemon and cached whether or not the Dockerfile copies from it.
	bootstrapIgnoreFile = "dockerignore"
	// runtimeImageRole names the postgres image in SBOM evidence. The bootstrap
	// image carries its own role from the recipe that builds it.
	runtimeImageRole = "runtime"
)

type Builder struct {
	services.BuilderServer
	*Service
}

func NewBuilder() *Builder {
	return &Builder{
		Service: NewService(),
	}
}

func (s *Builder) Load(ctx context.Context, req *builderv0.LoadRequest) (*builderv0.LoadResponse, error) {
	defer s.Wool.Catch()

	return s.Builder.LoadService(ctx, req, services.BuilderLoad{
		Settings:         s.Settings,
		Requirements:     requirements,
		FactoryTemplates: factoryFS,
		ResolveEndpoints: func(ctx context.Context, endpoints []*v0.Endpoint) error {
			endpoint, err := resources.FindTCPEndpoint(ctx, endpoints)
			if err != nil {
				return err
			}
			s.TcpEndpoint = endpoint
			s.Wool.Debug("endpoint", wool.Field("tcp", endpoint))
			return nil
		},
	})
}

func (s *Builder) Init(ctx context.Context, req *builderv0.InitRequest) (*builderv0.InitResponse, error) {
	defer s.Wool.Catch()

	return s.Builder.InitResponse()
}

func (s *Builder) Update(ctx context.Context, req *builderv0.UpdateRequest) (*builderv0.UpdateResponse, error) {
	defer s.Wool.Catch()

	return &builderv0.UpdateResponse{}, nil
}

func (s *Builder) Sync(ctx context.Context, req *builderv0.SyncRequest) (*builderv0.SyncResponse, error) {
	defer s.Wool.Catch()
	ctx = s.Wool.Inject(ctx)

	for environment := range s.Settings.ExternalInstances {
		if _, err := s.externalInstance(environment); err != nil {
			return s.Builder.SyncError(err)
		}
	}
	return s.Builder.SyncResponse()
}

// Audit scans the configured postgres image for known HIGH/CRITICAL CVEs.
func (s *Builder) Audit(ctx context.Context, req *builderv0.AuditRequest) (*builderv0.AuditResponse, error) {
	defer s.Wool.Catch()
	ctx = s.Wool.Inject(ctx)
	return s.Builder.AuditContainer(ctx, req, s.dockerImage().FullName())
}

// SBOM inventories the service's software. Source scope keeps the package-level
// scan of the configured postgres image; image scope serves evidence bound to
// the digest and platform each shipped image was actually scanned from.
func (s *Builder) SBOM(ctx context.Context, req *builderv0.SBOMRequest) (*builderv0.SBOMResponse, error) {
	defer s.Wool.Catch()
	ctx = s.Wool.Inject(ctx)
	if req.GetScope() != builderv0.SBOMScope_SBOM_SCOPE_IMAGE {
		return s.Builder.SBOMContainer(ctx, s.dockerImage().FullName())
	}
	// The bootstrap image is built by the caller from the emitted recipe, so its
	// digest exists only once that build has run. Covering the runtime image
	// alone would report complete coverage of an image set this service does not
	// fully ship, so the caller's subjects are a precondition rather than
	// something to work around.
	if len(req.GetSubjects()) == 0 {
		return s.Builder.SBOMImageSubjectsRequired()
	}
	runtimeSubjects, err := s.runtimeImageSubjects()
	if err != nil {
		return s.Builder.SBOMImageError(err)
	}
	// The caller's own subjects lead, so a failure among the images it asked
	// about is reported as itself rather than behind the one this agent adds.
	return s.Builder.SBOMImages(ctx, distinctSubjects(req.GetSubjects(), runtimeSubjects))
}

// distinctSubjects drops subjects that are identical in every field. Each
// subject costs a full image scan, and a repeated one carries no association
// the first does not already have. Subjects that differ in service or role are
// kept: that is how one digest still names every service it covers.
func distinctSubjects(groups ...[]*builderv0.ImageSubject) []*builderv0.ImageSubject {
	seen := map[string]bool{}
	var subjects []*builderv0.ImageSubject
	for _, group := range groups {
		for _, subject := range group {
			key := strings.Join([]string{
				subject.GetReference(),
				subject.GetDigest(),
				subject.GetPlatform(),
				subject.GetRole(),
				subject.GetService(),
			}, "|")
			if seen[key] {
				continue
			}
			seen[key] = true
			subjects = append(subjects, subject)
		}
	}
	return subjects
}

// runtimeImageSubjects describes the postgres image the workload runs. It is
// deployed rather than built, so it appears in no build plan and no caller
// derives a subject for it — without this the image the database actually runs
// would never be inventoried. The pin rides in the reference rather than in the
// digest field: evidence binds to the platform's child manifest, which is what
// each subject's scan resolves out of the manifest list the deployment names.
func (s *Service) runtimeImageSubjects() ([]*builderv0.ImageSubject, error) {
	configured := s.dockerImage()
	if configured == nil {
		return nil, fmt.Errorf("docker-image %q is not a name:tag reference", s.Settings.Image)
	}
	platforms := image.Platforms
	if s.Settings != nil && s.Settings.Image != "" {
		for _, platform := range s.Settings.ImagePlatforms {
			if err := validatePlatform("docker-image-platforms", platform); err != nil {
				return nil, err
			}
		}
		// An override that declares no platforms leaves the platform unstated:
		// exact for a single-platform image, and for a multi-platform one the
		// scanner refuses to pick one rather than mislabel the evidence.
		platforms = s.Settings.ImagePlatforms
		if len(platforms) == 0 {
			platforms = []string{""}
		}
	}
	return sbom.ExpectedFromImageReference(sbom.PublishedImage{
		Service:   s.Unique(),
		Role:      runtimeImageRole,
		Reference: configured.FullName(),
		Platforms: platforms,
	})
}

// Upgrade reports an available tag bump for the managed postgres image.
func (s *Builder) Upgrade(ctx context.Context, req *builderv0.UpgradeRequest) (*builderv0.UpgradeResponse, error) {
	defer s.Wool.Catch()
	ctx = s.Wool.Inject(ctx)
	res, err := upgrade.Docker(ctx, image.FullName(), upgrade.Options{
		IncludeMajor: req.IncludeMajor,
		DryRun:       req.DryRun,
	})
	if err != nil {
		return s.Builder.UpgradeError(err)
	}
	return s.Builder.UpgradeResponse(res.Changes, res.LockfileDiff)
}

// DockerTemplating renders the bootstrap image: the Dockerfile, the generated
// bootstrap program, and the SQL it applies. Every field is derived from the
// schema plan, so the image can only carry what the plan declares.
type DockerTemplating struct {
	MigrationConnectionEnvironment string
	// RuntimeAccessLockID is the advisory-lock expression the bootstrap script
	// takes, shared verbatim with the agent so the two cannot drift apart.
	RuntimeAccessLockID     string
	ReadinessTimeoutSeconds int
	ReadOnlyRole            string
	ReadWriteRole           string
	Schemas                 []string
	ReadWriteRoles          []string
	// DefaultReadWriteRole is the application role the managed read-write login
	// selects on connect. See defaultRuntimeReadWriteRole.
	DefaultReadWriteRole string
	// Logins are the declared runtime login principals the bootstrap Job
	// provisions beside the managed read-write login.
	Logins     []BootstrapLogin
	Extensions []BootstrapExtension
	Lineages   []BootstrapLineage
}

// Bootstrap resolves the locked bootstrap inputs the Dockerfile renders from. A
// method, not a field: the template dereferences it on its first line, so a
// constructed value must not be able to omit it.
func (DockerTemplating) Bootstrap() *bootstrapImageLock {
	return bootstrapLock
}

// BootstrapLogin is one declared runtime login as runtime-access.sql sees it:
// its role, the environment variable its password arrives on, its exclusive
// delegated role set and the one it defaults to.
type BootstrapLogin struct {
	Role             string
	PasswordVariable string
	ReadWriteRoles   []string
	DefaultRole      string
}

func bootstrapLogins(logins []runtimeLogin) []BootstrapLogin {
	out := make([]BootstrapLogin, 0, len(logins))
	for _, login := range logins {
		out = append(out, BootstrapLogin{
			Role:             login.role,
			PasswordVariable: login.passwordKey,
			ReadWriteRoles:   login.readWriteRoles,
			DefaultRole:      defaultRuntimeReadWriteRole(login.readWriteRoles),
		})
	}
	return out
}

// BootstrapLineage is one migration lineage as the generated bootstrap program
// sees it: the staged directory inside the image and the ledger it owns.
type BootstrapLineage struct {
	Label  string
	Stage  string
	Ledger string
}

// bootstrapLineages projects the plan's lineages onto the staged layout the
// image carries, in declared order.
func bootstrapLineages(plan *schemaPlan) []BootstrapLineage {
	lineages := make([]BootstrapLineage, 0, len(plan.lineages))
	for _, lineage := range plan.lineages {
		lineages = append(lineages, BootstrapLineage{
			Label:  lineage.label(),
			Stage:  lineage.stage,
			Ledger: lineage.trackingTable(),
		})
	}
	return lineages
}

// BootstrapExtension is one extension as the generated SQL sees it. A required
// extension aborts the bootstrap when it cannot be created, exactly as it fails
// the local runtime's readiness; an optional one is reported and skipped.
type BootstrapExtension struct {
	Name     string
	Required bool
}

func bootstrapExtensions(plan *schemaPlan) []BootstrapExtension {
	extensions := make([]BootstrapExtension, 0, len(plan.extensions))
	for _, extension := range plan.extensions {
		extensions = append(extensions, BootstrapExtension{Name: extension.name, Required: extension.required})
	}
	return extensions
}

func (*Builder) BuildCapabilities(context.Context, *builderv0.BuildCapabilitiesRequest) (*builderv0.BuildCapabilitiesResponse, error) {
	return &builderv0.BuildCapabilitiesResponse{BuildxSelection: true}, nil
}

func (s *Builder) Build(ctx context.Context, req *builderv0.BuildRequest) (*builderv0.BuildResponse, error) {
	defer s.Wool.Catch()

	s.Wool.Debug("building database bootstrap image")

	ctx = s.Wool.Inject(ctx)

	// The emitted bootstrap still owns password-authenticated login roles.
	// External-identity deployment metadata does not make that SQL compatible
	// with cloud-managed logins. Fail before deleting/staging caller output
	// until an external-identity bootstrap is implemented.
	if err := s.validateAuthMode(); err != nil {
		return s.Builder.BuildError(err)
	}
	if s.externalIdentity() {
		return s.Builder.BuildError(fmt.Errorf("external-identity bootstrap generation is unsupported: the password bootstrap must not rewrite cloud-managed login roles"))
	}

	if req.GetOutputDirectory() == "" {
		return s.Builder.BuildError(fmt.Errorf("output_directory is required: the CLI executes bootstrap image builds"))
	}

	dockerRequest, err := s.Builder.DockerBuildRequest(ctx, req)
	if err != nil {
		return nil, s.Wool.Wrapf(err, "can only do docker build request")
	}

	img := s.DockerImage(dockerRequest)

	if !dockerhelpers.IsValidDockerImageName(img.Name) {
		return s.Builder.BuildError(fmt.Errorf("invalid docker image name: %s", img.Name))
	}

	// The declared schema prerequisites are resolved here as well as at runtime,
	// so a typo'd source path or a colliding lineage fails the build instead of
	// producing a bootstrap image that quietly ships an incomplete schema. The
	// build then packages exactly what that resolution returned, so the image
	// applies the same lineages and extensions the runtime does.
	prerequisites, err := s.resolveSchemaPrerequisites()
	if err != nil {
		return s.Builder.BuildError(err)
	}
	if err = s.Settings.Timeouts.validate(); err != nil {
		return s.Builder.BuildError(err)
	}
	plan, err := buildSchemaPlan(prerequisites, s.Settings)
	if err != nil {
		return s.Builder.BuildError(err)
	}
	logins, err := s.runtimeLogins()
	if err != nil {
		return s.Builder.BuildError(err)
	}
	if err = plan.attest(); err != nil {
		return s.Builder.BuildError(err)
	}
	s.reportSchemaPrerequisites(prerequisites)
	docker := DockerTemplating{
		MigrationConnectionEnvironment: migrationConnectionEnvironmentKey,
		RuntimeAccessLockID:            runtimeAccessLockID,
		ReadinessTimeoutSeconds:        s.Settings.Timeouts.BootstrapReadinessSeconds(),
		ReadOnlyRole:                   plan.access.readOnlyRole,
		ReadWriteRole:                  plan.access.readWriteRole,
		Schemas:                        plan.access.schemas,
		ReadWriteRoles:                 plan.access.readWriteRoles,
		DefaultReadWriteRole:           defaultRuntimeReadWriteRole(plan.access.readWriteRoles),
		Logins:                         bootstrapLogins(logins),
		Extensions:                     bootstrapExtensions(plan),
		Lineages:                       bootstrapLineages(plan),
	}

	return s.buildRecipe(ctx, req.GetOutputDirectory(), img, plan, docker)
}

// buildRecipe renders the bootstrap image's recipe into the caller-owned output
// directory and returns a reproducible build plan instead of running docker
// itself. The CLI builds the emitted recipe multi-arch and pushes a manifest
// list, so a consumer can rebuild the image without the agent toolchain.
// The CLI resolves the recipe's "." context to the service directory
// (s.Location), not the recipe tree, so the bootstrap tree the Dockerfile COPYs
// is staged into both: into the service directory for the build the CLI runs,
// and into the recipe tree so the emitted artifact is a self-contained context
// a consumer can build directly. Both stagings write identical bytes.
func (s *Builder) buildRecipe(
	ctx context.Context,
	outputDirectory string,
	img *resources.DockerImage,
	plan *schemaPlan,
	docker DockerTemplating,
) (*builderv0.BuildResponse, error) {
	// The build plan inventories the whole output directory and the recipe
	// context is its root, so any pre-existing content the caller left here
	// would be digested into the plan and copied into the image. Empty the
	// directory the agent fully owns before rendering, as the deployment
	// emitter does.
	if err := shared.EmptyDir(ctx, outputDirectory); err != nil {
		return s.Builder.BuildError(err)
	}

	if err := s.Templates(ctx, docker, services.WithBuilder(builderFS).WithDestination("%s", filepath.Join(outputDirectory, "builder"))); err != nil {
		return s.Builder.BuildError(err)
	}

	for _, contextRoot := range []string{s.Location, outputDirectory} {
		if err := s.stageBootstrapContext(ctx, plan, docker, contextRoot); err != nil {
			return s.Builder.BuildError(err)
		}
	}

	buildPlan, err := services.BuildDockerBuildPlan(outputDirectory, []*builderv0.DockerBuildRecipe{{
		Name:         "bootstrap",
		Dockerfile:   "builder/Dockerfile",
		Context:      ".",
		Dockerignore: bootstrapDirectory + "/" + bootstrapIgnoreFile,
		Image:        img.FullName(),
		Platforms:    bootstrapRecipePlatforms(),
		// The recipe carries the resolved bootstrap inputs it was rendered from, so a
		// consumer reads the base, package and migrate identities off the plan
		// instead of re-resolving them.
		BuildArgs: docker.Bootstrap().RecipeBuildArgs(),
	}})
	if err != nil {
		return s.Builder.BuildError(err)
	}

	s.Builder.WithBuildPlan(buildPlan)
	return s.Builder.BuildResponse()
}

// stageBootstrapContext writes the complete bootstrap artifact into a build
// context root: the generated bootstrap program and SQL, the plan identity, the
// checksum manifest, and one immutable copy of every resolved migration source
// under its own staged directory. Sibling sources live outside the build
// context, so staging is what makes them reachable at all — a Dockerfile COPY
// cannot leave its context.
//
// The tree is built beside its destination and swapped in, never mutated in
// place. The image is built later by a separate process reading this same
// directory, so a reader must never observe a half-written tree.
func (s *Builder) stageBootstrapContext(
	ctx context.Context,
	plan *schemaPlan,
	docker DockerTemplating,
	contextRoot string,
) error {
	root := filepath.Join(contextRoot, bootstrapDirectory)
	if err := assertBootstrapDirectoryIsAgentOwned(root); err != nil {
		return err
	}
	staging, err := os.MkdirTemp(contextRoot, ".bootstrap-staging-")
	if err != nil {
		return err
	}
	defer func() { _ = os.RemoveAll(staging) }()

	if err = s.Templates(ctx, docker, services.WithTemplate(bootstrapFS, "bootstrap", "").WithDestination("%s", staging)); err != nil {
		return err
	}
	if err = stageBootstrapMigrate(staging); err != nil {
		return err
	}
	// Every resolved lineage is staged, including one that carries no migration
	// yet, so the plan artifact's staged paths always describe real directories.
	for _, lineage := range plan.lineages {
		if err = stageLineage(ctx, lineage, filepath.Join(staging, "sources", lineage.stage)); err != nil {
			return fmt.Errorf("stage migration source %q: %w", lineage.label(), err)
		}
	}
	artifact, err := json.MarshalIndent(plan.artifact(), "", "  ")
	if err != nil {
		return err
	}
	if err = os.WriteFile(filepath.Join(staging, "plan.json"), append(artifact, '\n'), 0o644); err != nil {
		return err
	}
	if err = os.WriteFile(filepath.Join(staging, stagedChecksumFile), plan.stagedChecksums(), 0o644); err != nil {
		return err
	}
	// The recipe digest covers each file's mode and the bootstrap Job reads this
	// tree as a non-root user, so the emitting machine's umask must not decide
	// either the published digest or whether the Job can read its own program.
	if err = normalizeStagedModes(staging); err != nil {
		return err
	}

	if err = os.RemoveAll(root); err != nil {
		return err
	}
	if err = os.Rename(staging, root); err != nil {
		return err
	}
	if err = s.renderRuntimeAccess(ctx, docker, contextRoot); err != nil {
		return err
	}
	return os.Chmod(filepath.Join(contextRoot, runtimeAccessFile), 0o644)
}

// assertBootstrapDirectoryIsAgentOwned refuses to replace a bootstrap directory
// the agent did not write. The staging root sits in the user's service
// directory, where "bootstrap" is a plausible name for hand-authored seed SQL,
// and staging deletes the directory it claims — so a directory without the
// agent's marker fails the build instead of being destroyed.
func assertBootstrapDirectoryIsAgentOwned(root string) error {
	if _, err := os.Stat(root); err != nil {
		if os.IsNotExist(err) {
			return nil
		}
		return err
	}
	marker, err := os.ReadFile(filepath.Join(root, bootstrapMarkerFile))
	if err == nil && strings.HasPrefix(string(marker), bootstrapMarker) {
		return nil
	}
	return fmt.Errorf(
		"%s already exists and was not generated by codefly; move it aside — the postgres build owns that directory and regenerates it on every build",
		root)
}

// normalizeStagedModes gives every staged file and directory a fixed mode.
func normalizeStagedModes(root string) error {
	return filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		if entry.IsDir() {
			return os.Chmod(path, 0o755)
		}
		return os.Chmod(path, 0o644)
	})
}

// stageLineage copies one lineage's inventoried files into its staged directory
// and re-checks each digest, so the plan artifact and the checksum manifest
// describe exactly the bytes the image carries even if a file changed while the
// build was running.
func stageLineage(ctx context.Context, lineage schemaLineage, destination string) error {
	if err := os.MkdirAll(destination, 0o755); err != nil {
		return err
	}
	for _, file := range lineage.files {
		staged := filepath.Join(destination, file.name)
		if err := shared.CopyFile(ctx, filepath.Join(lineage.dir, file.name), staged); err != nil {
			return err
		}
		digest, err := fileDigest(staged)
		if err != nil {
			return err
		}
		if digest != file.digest {
			return fmt.Errorf("%s changed while it was being staged", file.name)
		}
	}
	return nil
}

// renderRuntimeAccess renders runtime-access.sql into the build context root, the
// directory docker builds from. The Dockerfile COPYs it from there, so it must
// sit beside the staged bootstrap tree rather than under builder/.
func (s *Builder) renderRuntimeAccess(ctx context.Context, docker DockerTemplating, contextRoot string) error {
	return s.Templates(ctx, docker, services.WithTemplate(runtimeFS, "runtime", "").WithDestination("%s", contextRoot))
}

func (s *Builder) Deploy(ctx context.Context, req *builderv0.DeploymentRequest) (*builderv0.DeploymentResponse, error) {
	defer s.Wool.Catch()

	if err := s.Settings.Timeouts.validate(); err != nil {
		return s.Builder.DeployError(err)
	}
	parameters := &DeploymentTemplateParameters{
		WithBootstrap:               true,
		ManagedImage:                s.dockerImage().FullName(),
		DatabaseName:                s.DatabaseName,
		BootstrapJobDeadlineSeconds: s.Settings.Timeouts.BootstrapJobSeconds(),
	}
	var restrictedConfiguration *v0.Configuration
	response, err := s.Builder.DeployKustomize(ctx, req, services.KustomizeDeployment{
		EnvironmentVariables: s.EnvironmentVariables,
		Templates:            deploymentFS,
		Parameters:           parameters,
		Prepare: func(ctx context.Context, deployment *services.KustomizeDeploymentContext) error {
			configuration, prepareErr := s.prepareDeployment(ctx, deployment, parameters)
			if prepareErr != nil {
				return prepareErr
			}
			bootstrapJobName, nameErr := s.immutableBootstrapJobName(deployment, parameters)
			if nameErr != nil {
				return nameErr
			}
			parameters.BootstrapJobName = bootstrapJobName
			s.Wool.Debug("exporting configuration", wool.Field("conf", resources.MakeConfigurationSummary(configuration)))
			if restrictedOutput(deployment.Profile) {
				restrictedConfiguration = configuration
				return nil
			}
			return deployment.ExportConfiguration(ctx, configuration)
		},
	})
	if err != nil ||
		response.GetState().GetState() != builderv0.DeploymentStatus_SUCCESS ||
		restrictedConfiguration == nil {
		return response, err
	}
	response.Configuration = restrictedConfiguration
	return response, nil
}

const bootstrapJobTemplatePath = "templates/deployment/kustomize/base/job.yaml.tmpl"

func (s *Builder) immutableBootstrapJobName(
	deployment *services.KustomizeDeploymentContext,
	parameters *DeploymentTemplateParameters,
) (string, error) {
	service := shared.ToDNSCase(s.Identity.Name)
	if service == "" {
		return "", fmt.Errorf("bootstrap service name is required")
	}

	source, err := fs.ReadFile(deploymentFS, bootstrapJobTemplatePath)
	if err != nil {
		return "", fmt.Errorf("read bootstrap Job template: %w", err)
	}
	jobTemplate, err := template.New(bootstrapJobTemplatePath).Parse(string(source))
	if err != nil {
		return "", fmt.Errorf("parse bootstrap Job template: %w", err)
	}
	renderContext := &services.DeploymentWrapper{
		DeploymentBase: &services.DeploymentBase{
			Information: s.Information,
			Namespace:   deployment.Kubernetes.GetNamespace(),
			Image:       s.DockerImage(deployment.Kubernetes.GetBuildContext()),
			Profile:     deployment.Profile,
			Restricted:  restrictedOutput(deployment.Profile),
		},
		Deployment: services.DeploymentParameters{Parameters: parameters},
	}
	var rendered bytes.Buffer
	if err = jobTemplate.Execute(&rendered, renderContext); err != nil {
		return "", fmt.Errorf("render bootstrap Job template: %w", err)
	}
	var job struct {
		Spec struct {
			Template yaml.Node `yaml:"template"`
		} `yaml:"spec"`
	}
	if err = yaml.Unmarshal(rendered.Bytes(), &job); err != nil {
		return "", fmt.Errorf("parse rendered bootstrap Job: %w", err)
	}
	if job.Spec.Template.Kind == 0 {
		return "", fmt.Errorf("rendered bootstrap Job is missing spec.template")
	}
	podTemplate, err := yaml.Marshal(&job.Spec.Template)
	if err != nil {
		return "", fmt.Errorf("encode bootstrap Job pod template: %w", err)
	}
	contentDigest := sha256.Sum256(podTemplate)

	const suffixLength = 12
	const maxServiceLength = 63 - 1 - suffixLength
	if len(service) > maxServiceLength {
		service = strings.TrimRight(service[:maxServiceLength], "-")
	}
	return service + "-" + hex.EncodeToString(contentDigest[:])[:suffixLength], nil
}

func (s *Builder) prepareDeployment(
	ctx context.Context,
	deployment *services.KustomizeDeploymentContext,
	parameters *DeploymentTemplateParameters,
) (*v0.Configuration, error) {
	req := deployment.Request
	logins, err := s.runtimeLogins()
	if err != nil {
		return nil, err
	}
	instance, binding, err := s.deploymentNetworkInstance(
		ctx,
		req.GetNetworkMappings(),
		req.GetEnvironment().GetName(),
	)
	if err != nil {
		return nil, err
	}
	if binding == nil {
		// The Service publishes the port core allocated to the endpoint — the
		// one every consumer dials — and targets 5432. Same mechanism as redis:
		// the mapping the CLI hands this Deploy carries our own endpoint.
		parameters.ServicePort = instance.GetPort()
	}
	if binding != nil {
		if s.externalIdentity() {
			return nil, fmt.Errorf("external-instance deployment does not support auth-mode %q: managed bootstrap generation requires password authentication", authModeExternalIdentity)
		}
		readOnlyRole, readWriteRole := runtimeRoleNames(s.DatabaseName)
		parameters.ExternalInstance = true
		parameters.ExternalHost = binding.Host
		parameters.ExternalPort = binding.port()
		parameters.ExternalSSLMode = "prefer"
		if s.WithoutSSL {
			parameters.ExternalSSLMode = "disable"
		}
		parameters.ReadOnlyRole = readOnlyRole
		parameters.ReadWriteRole = readWriteRole
		parameters.ExternalBindingID = externalBindingID(req.GetEnvironment().GetName(), binding)
	}
	withSSL := s.deploymentWithSSL(binding)
	if restrictedOutput(deployment.Profile) {
		workloadReferences, referencesErr := s.selectPromotableSecretReferences(
			deployment.Kubernetes.GetSecretReferences(),
			binding != nil,
			logins,
		)
		if referencesErr != nil {
			return nil, referencesErr
		}
		parameters.StatefulSetSecretReferences = workloadReferences.StatefulSet
		parameters.BootstrapJobSecretReferences = workloadReferences.BootstrapJob
		if binding == nil && !s.externalIdentity() {
			// The migration owner reaches the managed server the way it reaches
			// an external binding: through libpq's environment, from the owner
			// user and password the server itself is initialized with. No
			// assembled owner connection string exists for anyone to store.
			host, port, splitErr := net.SplitHostPort(instance.GetAddress())
			if splitErr != nil {
				return nil, fmt.Errorf("postgres in-cluster address %q: %w", instance.GetAddress(), splitErr)
			}
			parameters.OwnerFromLibpqEnvironment = true
			parameters.OwnerHost = host
			parameters.OwnerPort = port
			parameters.OwnerSSLMode = postgresSSLMode(instance.GetAddress(), withSSL)
		}
		return s.promotableConnectionConfiguration(instance, withSSL), nil
	}

	configuration, err := s.CreateConnectionConfiguration(ctx, req.GetConfiguration(), instance, withSSL)
	if err != nil {
		return nil, err
	}
	ownerConnection, err := s.createOwnerConnectionString(ctx, req.GetConfiguration(), instance.Address, withSSL)
	if err != nil {
		return nil, err
	}
	// These raw workload values stay in the ephemeral profile's generated
	// Secret; callers receive only the managed-resource configuration.
	deployment.AddSecrets(
		resources.Env("POSTGRES_USER", s.postgresUser),
		resources.Env("POSTGRES_PASSWORD", s.postgresPassword),
		resources.Env("POSTGRES_DB", s.DatabaseName),
		resources.Env("POSTGRES_READ_ONLY_PASSWORD", s.readOnlyPassword),
		resources.Env("POSTGRES_READ_WRITE_PASSWORD", s.readWritePassword),
		resources.Env(migrationConnectionEnvironmentKey, ownerConnection),
	)
	for _, login := range logins {
		deployment.AddSecrets(resources.Env(login.passwordKey, s.loginPasswords[login.name]))
	}
	if binding != nil {
		deployment.AddSecrets(
			resources.Env("PGUSER", s.postgresUser),
			resources.Env("PGPASSWORD", s.postgresPassword),
			resources.Env(externalReadOnlyConnectionKey, configurationValueByKey(configuration, readOnlyConnectionKey)),
			resources.Env(externalReadWriteConnectionKey, configurationValueByKey(configuration, readWriteConnectionKey)),
		)
	}
	return configuration, nil
}

// deploymentWithSSL reports whether deployed connections may leave sslmode to
// the client. The managed StatefulSet runs this agent's runtime image, which
// configures no TLS, so a client that requires it by default — lib/pq, which
// the bootstrap Job's migrate uses — is refused by the server this agent itself
// deployed. Connections to it therefore pin sslmode=disable whatever without-ssl
// says; without-ssl decides only for an external instance, whose TLS this agent
// does not control. (Inside the cluster, transport encryption is the mesh's.)
func (s *Builder) deploymentWithSSL(binding *ExternalInstance) bool {
	if binding == nil {
		return false
	}
	return !s.WithoutSSL
}

func (s *Builder) deploymentNetworkInstance(
	ctx context.Context,
	mappings []*v0.NetworkMapping,
	environment string,
) (*v0.NetworkInstance, *ExternalInstance, error) {
	binding, err := s.externalInstance(environment)
	if err != nil {
		return nil, nil, err
	}
	if binding == nil {
		instance, findErr := resources.FindNetworkInstanceInNetworkMappings(
			ctx,
			mappings,
			s.TcpEndpoint,
			resources.NewPublicNetworkAccess(),
		)
		return instance, nil, findErr
	}
	port := binding.port()
	address := net.JoinHostPort(binding.Host, strconv.Itoa(int(port)))
	return &v0.NetworkInstance{
		Access:   resources.NewPublicNetworkAccess(),
		Hostname: binding.Host,
		Host:     address,
		Port:     uint32(port),
		Address:  address,
	}, binding, nil
}

func (s *Service) externalInstance(environment string) (*ExternalInstance, error) {
	if len(s.Settings.ExternalInstances) == 0 {
		return nil, nil
	}
	if strings.TrimSpace(environment) == "" {
		return nil, fmt.Errorf("external-instances requires a named deployment environment")
	}
	binding, configured := s.Settings.ExternalInstances[environment]
	if !configured {
		return nil, fmt.Errorf("external-instances has no binding for deployment environment %q", environment)
	}
	if binding.Host == "" {
		return nil, fmt.Errorf("external-instance host is required")
	}
	if binding.Host != strings.TrimSpace(binding.Host) ||
		strings.ContainsAny(binding.Host, " \t\r\n/?#") ||
		strings.Contains(binding.Host, "://") ||
		(strings.Contains(binding.Host, ":") && net.ParseIP(binding.Host) == nil) {
		return nil, fmt.Errorf("external-instance host %q must be a hostname or IP address without a scheme, port, or path", binding.Host)
	}
	if binding.DatabaseName != s.DatabaseName {
		return nil, fmt.Errorf("external-instance database-name %q does not match declared database-name %q", binding.DatabaseName, s.DatabaseName)
	}
	readOnlyRole, readWriteRole := runtimeRoleNames(s.DatabaseName)
	declaredRoles, err := normalizedRuntimeReadWriteRoles(s.RuntimeReadWriteRoles, readOnlyRole, readWriteRole)
	if err != nil {
		return nil, err
	}
	boundRoles, err := normalizedRuntimeReadWriteRoles(binding.RuntimeReadWriteRoles, readOnlyRole, readWriteRole)
	if err != nil {
		return nil, fmt.Errorf("external-instance: %w", err)
	}
	if !slices.Equal(boundRoles, declaredRoles) {
		return nil, fmt.Errorf("external-instance runtime-read-write-roles %v do not match declared runtime-read-write-roles %v", boundRoles, declaredRoles)
	}
	return &binding, nil
}

func (binding *ExternalInstance) port() uint16 {
	if binding.Port == 0 {
		return 5432
	}
	return binding.Port
}

func externalBindingID(environment string, binding *ExternalInstance) string {
	identity := strings.Join([]string{
		environment,
		binding.Host,
		strconv.Itoa(int(binding.port())),
		binding.DatabaseName,
		strings.Join(binding.RuntimeReadWriteRoles, "\x00"),
	}, "\x00")
	digest := sha256.Sum256([]byte(identity))
	return hex.EncodeToString(digest[:])
}

func configurationValueByKey(configuration *v0.Configuration, key string) string {
	for _, information := range configuration.GetInfos() {
		for _, value := range information.GetConfigurationValues() {
			if value.GetKey() == key {
				return value.GetValue()
			}
		}
	}
	return ""
}

type promotableWorkloadSecretReferences struct {
	StatefulSet  map[string]*builderv0.KubernetesSecretKeyReference
	BootstrapJob map[string]*builderv0.KubernetesSecretKeyReference
}

func (s *Builder) selectPromotableSecretReferences(
	configured map[string]*builderv0.KubernetesSecretKeyReference,
	external bool,
	logins []runtimeLogin,
) (*promotableWorkloadSecretReferences, error) {
	// The restricted deploy build never loads runtime credentials, so this is
	// the only place the auth mode is checked on this path: reject a mistyped
	// mode here rather than silently demanding password Secret references.
	if err := s.validateAuthMode(); err != nil {
		return nil, err
	}
	// External-identity mode holds no passwords, so the deploy build promotes no
	// credential Secret references; infra's guard forbids any Secret in the
	// db-auth stack.
	if s.externalIdentity() {
		return &promotableWorkloadSecretReferences{
			StatefulSet:  map[string]*builderv0.KubernetesSecretKeyReference{},
			BootstrapJob: map[string]*builderv0.KubernetesSecretKeyReference{},
		}, nil
	}
	if external {
		return s.selectExternalSecretReferences(configured)
	}
	statefulSetEnvironmentVariables := []string{
		"POSTGRES_USER",
		"POSTGRES_PASSWORD",
	}
	bootstrapJobEnvironmentVariables := []string{
		"POSTGRES_USER",
		"POSTGRES_READ_ONLY_PASSWORD",
		"POSTGRES_READ_WRITE_PASSWORD",
	}
	// The four managed primitives are authored outside this agent — the factory
	// scaffolds them into the service's own secret configuration — so a render
	// that reaches here without one is a misconfigured service, and saying so
	// is the point.
	primitives := []string{
		"POSTGRES_USER",
		"POSTGRES_PASSWORD",
		"POSTGRES_READ_ONLY_PASSWORD",
		"POSTGRES_READ_WRITE_PASSWORD",
	}
	selected := make(map[string]*builderv0.KubernetesSecretKeyReference, len(primitives)+len(logins)+2)
	secretName := ""
	for _, environmentVariable := range primitives {
		configurationKey := resources.ServiceSecretConfigurationKeyFromUnique(
			s.Unique(),
			"postgres",
			environmentVariable,
		)
		reference := configured[configurationKey]
		if reference == nil || reference.GetName() == "" || reference.GetKey() == "" {
			return nil, fmt.Errorf("postgres deployment requires a typed Kubernetes Secret reference for %s", configurationKey)
		}
		if reference.GetOptional() {
			return nil, fmt.Errorf("%s Kubernetes Secret reference must not be optional", configurationKey)
		}
		if secretName == "" {
			secretName = reference.GetName()
		} else if secretName != reference.GetName() {
			return nil, fmt.Errorf("postgres credential references must use one Kubernetes Secret")
		}
		selected[environmentVariable] = reference
	}
	// Each declared login's password is one more primitive: the bootstrap Job
	// sets it on the login's role, and consumers' connections are templated
	// over it. It lives in the same Secret as the others — and, unlike them,
	// this agent is what names it, so this agent is what declares it. The set
	// comes from the same resolved logins runtime-access.sql iterates, so the
	// SQL and the references it reads cannot drift.
	for _, login := range logins {
		reference, err := s.loginPasswordSecretReference(configured, secretName, login)
		if err != nil {
			return nil, err
		}
		selected[login.passwordKey] = reference
		bootstrapJobEnvironmentVariables = append(bootstrapJobEnvironmentVariables, login.passwordKey)
	}
	// The Job connects as the migration owner through libpq's environment,
	// from the same primitives the StatefulSet initializes the server with —
	// never from an assembled connection string an operator has to store.
	selected["PGUSER"] = selected["POSTGRES_USER"]
	selected["PGPASSWORD"] = selected["POSTGRES_PASSWORD"]
	bootstrapJobEnvironmentVariables = append(bootstrapJobEnvironmentVariables, "PGUSER", "PGPASSWORD")
	selectForWorkload := func(environmentVariables []string) map[string]*builderv0.KubernetesSecretKeyReference {
		workloadReferences := make(map[string]*builderv0.KubernetesSecretKeyReference, len(environmentVariables))
		for _, environmentVariable := range environmentVariables {
			workloadReferences[environmentVariable] = selected[environmentVariable]
		}
		return workloadReferences
	}
	return &promotableWorkloadSecretReferences{
		StatefulSet:  selectForWorkload(statefulSetEnvironmentVariables),
		BootstrapJob: selectForWorkload(bootstrapJobEnvironmentVariables),
	}, nil
}

// loginPasswordSecretReference resolves the Secret key a declared login's
// password arrives on in a restricted render.
//
// A declared login's password key is named by this agent — resolveRuntimeLogins
// derives POSTGRES_<NAME>_PASSWORD from the declaration, and runtime-access.sql
// reads exactly that variable — so nothing outside the agent knows the key
// exists until a render says so. The restricted render IS that declaration: the
// CLI projects a service's ExternalSecret from precisely the non-optional
// secretKeyRefs its manifests carry, so a key the agent refuses to render is a
// key the secret store is never asked to hold. Demanding the reference first
// closes the loop on itself — no render, no declared key, no value, no render —
// which is why a service declaring its first login could not deploy at all.
// The agent therefore derives the reference into the one Secret the render
// already uses, with the configuration key the CLI itself would have produced.
//
// This declares the key; it does not mandate a distinct value. Locally the
// password stays optional and is derived from the owner secret when absent
// (LoadConfiguration), exactly as the reader's and writer's are.
//
// An explicitly configured reference still wins — a service that does author
// the primitive keeps that reference — and is held to the same invariants as
// the managed primitives: never optional, always the one Secret.
func (s *Builder) loginPasswordSecretReference(
	configured map[string]*builderv0.KubernetesSecretKeyReference,
	secretName string,
	login runtimeLogin,
) (*builderv0.KubernetesSecretKeyReference, error) {
	configurationKey := resources.ServiceSecretConfigurationKeyFromUnique(
		s.Unique(),
		"postgres",
		login.passwordKey,
	)
	reference := configured[configurationKey]
	if reference == nil || reference.GetName() == "" || reference.GetKey() == "" {
		return &builderv0.KubernetesSecretKeyReference{Name: secretName, Key: configurationKey}, nil
	}
	if reference.GetOptional() {
		return nil, fmt.Errorf("%s Kubernetes Secret reference must not be optional", configurationKey)
	}
	if reference.GetName() != secretName {
		return nil, fmt.Errorf("postgres credential references must use one Kubernetes Secret")
	}
	return reference, nil
}

func (s *Builder) selectExternalSecretReferences(
	configured map[string]*builderv0.KubernetesSecretKeyReference,
) (*promotableWorkloadSecretReferences, error) {
	required := []struct {
		environmentVariable string
		configurationKey    string
	}{
		{environmentVariable: "POSTGRES_USER", configurationKey: "POSTGRES_USER"},
		{environmentVariable: "PGUSER", configurationKey: "POSTGRES_USER"},
		{environmentVariable: "PGPASSWORD", configurationKey: "POSTGRES_PASSWORD"},
		{environmentVariable: "POSTGRES_READ_ONLY_PASSWORD", configurationKey: "POSTGRES_READ_ONLY_PASSWORD"},
		{environmentVariable: "POSTGRES_READ_WRITE_PASSWORD", configurationKey: "POSTGRES_READ_WRITE_PASSWORD"},
		{environmentVariable: externalReadOnlyConnectionKey, configurationKey: readOnlyConnectionKey},
		{environmentVariable: externalReadWriteConnectionKey, configurationKey: readWriteConnectionKey},
	}
	selected := make(map[string]*builderv0.KubernetesSecretKeyReference, len(required))
	secretName := ""
	for _, item := range required {
		key := resources.ServiceSecretConfigurationKeyFromUnique(s.Unique(), "postgres", item.configurationKey)
		reference := configured[key]
		if reference == nil || reference.GetName() == "" || reference.GetKey() == "" {
			return nil, fmt.Errorf("external postgres deployment requires a typed Kubernetes Secret reference for %s", key)
		}
		if reference.GetOptional() {
			return nil, fmt.Errorf("%s Kubernetes Secret reference must not be optional", key)
		}
		if secretName == "" {
			secretName = reference.GetName()
		} else if secretName != reference.GetName() {
			return nil, fmt.Errorf("external postgres credential references must use one Kubernetes Secret")
		}
		selected[item.environmentVariable] = reference
	}
	return &promotableWorkloadSecretReferences{
		StatefulSet:  map[string]*builderv0.KubernetesSecretKeyReference{},
		BootstrapJob: selected,
	}, nil
}

type create struct {
	DatabaseName string
	TableName    string
}

func (s *Builder) Create(ctx context.Context, req *builderv0.CreateRequest) (*builderv0.CreateResponse, error) {
	defer s.Wool.Catch()

	// Use defaults
	s.Settings.HotReload = true
	if s.Settings.DatabaseName == "" {
		s.Settings.DatabaseName = s.Base.Identity.Module
	}

	c := create{DatabaseName: s.Settings.DatabaseName, TableName: s.Builder.Service.Name}

	err := s.Templates(ctx, c, services.WithFactory(factoryFS))
	if err != nil {
		return s.Builder.CreateError(err)
	}

	err = s.CreateEndpoints(ctx)
	if err != nil {
		return s.Builder.CreateErrorf(err, "cannot create endpoints")
	}

	s.Wool.Debug("created endpoints", wool.Field("endpoints", resources.MakeManyEndpointSummary(s.Endpoints)))

	return s.Builder.CreateResponse(ctx, s.Settings)
}

// restrictedOutput reports whether the deployment selects the restricted,
// portable output contract. It replaces services.IsRestrictedOutputProfile,
// retired in favour of a parsed profile: an unknown or unselected profile is
// now an ERROR rather than silently "not restricted", and it is read as
// RESTRICTED here -- the other direction would hand a restricted render the
// secrets it exists to refuse.
func restrictedOutput(profile builderv0.KubernetesOutputProfile) bool {
	parsed, err := services.ParseOutputProfile(profile)
	if err != nil {
		return true
	}
	return parsed.Restricted()
}

func (s *Builder) CreateEndpoints(ctx context.Context) error {
	tcp, err := resources.LoadTCPAPI(ctx)
	if err != nil {
		return s.Wool.Wrapf(err, "cannot load tcp api")
	}
	endpoint := s.Base.BaseEndpoint(standards.TCP)
	// PRIVATE, not the retired `external`: reach is visibility, addressing is
	// exposure, where it lives is location -- and on a store `external` was a
	// false claim either way, since the render allocates this service its own
	// in-cluster address. Every composed store already declares private.
	endpoint.Visibility = resources.VisibilityPrivate
	s.TcpEndpoint, err = resources.NewAPI(ctx, endpoint, resources.ToTCPAPI(tcp))
	s.Endpoints = []*v0.Endpoint{s.TcpEndpoint}
	return nil
}

func (s *Builder) Communicate(stream builderv0.Builder_CommunicateServer) error {
	asker := communicate.NewQuestionAsker(stream)
	_, err := asker.RunSequence(nil)
	return err
}

// all: so the scaffolded .gitignore (a dotfile go:embed skips by default) is
// carried into the factory tree and rendered into new services.
//
//go:embed all:templates/factory
var factoryFS embed.FS

//go:embed templates/builder
var builderFS embed.FS

// all: so the staged tree's .gitignore (a dotfile go:embed skips by default) is
// carried into the bootstrap tree it marks as agent-generated.
//
//go:embed all:templates/bootstrap
var bootstrapFS embed.FS

//go:embed templates/runtime
var runtimeFS embed.FS

//go:embed templates/deployment
var deploymentFS embed.FS