stack

package
v0.0.0-...-804b954 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package stack defines the typed desired-state input for operator-owned infrastructure.

Index

Constants

View Source 
const (
	// SearchAttributeTypeText is a full-text indexed Temporal field.
	SearchAttributeTypeText = "Text"
	// SearchAttributeTypeKeyword is an exact-match indexed Temporal field.
	SearchAttributeTypeKeyword = "Keyword"
	// SearchAttributeTypeInt is an integer indexed Temporal field.
	SearchAttributeTypeInt = "Int"
	// SearchAttributeTypeDouble is a floating-point indexed Temporal field.
	SearchAttributeTypeDouble = "Double"
	// SearchAttributeTypeBool is a boolean indexed Temporal field.
	SearchAttributeTypeBool = "Bool"
	// SearchAttributeTypeDatetime is a timestamp indexed Temporal field.
	SearchAttributeTypeDatetime = "Datetime"
	// SearchAttributeTypeKeywordList is a list-of-keywords indexed Temporal field.
	SearchAttributeTypeKeywordList = "KeywordList"
)

Variables

This section is empty.

Functions

func Check 

func Check(expected Rendered, candidate io.Reader) error

Check verifies candidate provenance and exact desired-state identity.

func RecordDeletedSecret 

func RecordDeletedSecret(authority *BootstrapAuthority, resource ResourceID, uid ObservedUID) error

RecordDeletedSecret durably records one exact precondition-deleted Secret for a retry.

func RemoveBootstrapAuthority 

func RemoveBootstrapAuthority(path string, expected BootstrapAuthority) error

RemoveBootstrapAuthority removes an unchanged capability after successful teardown.

func TransitionBootstrapAuthority 

func TransitionBootstrapAuthority(path string, current, next BootstrapAuthority) error

TransitionBootstrapAuthority atomically replaces an unchanged private capability with one bound to the next reviewed render digest.

func WriteBootstrapAuthority 

func WriteBootstrapAuthority(path string, authority BootstrapAuthority) error

WriteBootstrapAuthority creates a mode-0600 capability file without overwriting an existing path.

Types

type BlobResource 

type BlobResource struct {
	// Bucket is the explicit bucket name.
	Bucket string `json:"bucket"`
	// Prefix is the stack-owned key prefix.
	Prefix string `json:"prefix"`
	// EndpointReference names a declared service dependency rather than a storage URL.
	EndpointReference ResourceID `json:"endpoint_reference"`
	// EndpointPortName selects one declared Service port without inferring provider conventions.
	EndpointPortName string `json:"endpoint_port_name"`
	// CredentialReference names a SecretReference resource.
	CredentialReference ResourceID `json:"credential_reference"`
	// ReconcilerReference names the declared operator workload containing the pinned storage client.
	ReconcilerReference ResourceID `json:"reconciler_reference"`
}

BlobResource declares bucket/prefix ownership and finite retention.

type BootstrapAuthority 

type BootstrapAuthority struct {
	// Stack is the reviewed Stack identity.
	Stack string `json:"stack"`
	// Profile is the reviewed Stack profile.
	Profile Profile `json:"profile"`
	// Namespace is the exact rendered Namespace.
	Namespace string `json:"namespace"`
	// NamespaceUID is the immutable provider identity returned by bootstrap.
	NamespaceUID ObservedUID `json:"namespace_uid"`
	// RenderDigest records the reviewed rendering that created the Namespace.
	// Later reviewed revisions retain this namespace-bound authority.
	RenderDigest string `json:"render_digest"`
	// Nonce is private capability material; only its digest is stored on the Namespace.
	Nonce string `json:"nonce"`
	// DeletedSecrets records only exact Secret UIDs already removed by this capability.
	DeletedSecrets map[ResourceID]ObservedUID `json:"deleted_secrets,omitempty"`
	// contains filtered or unexported fields
}

BootstrapAuthority binds a mutating operator action to one Namespace that bootstrap created for exactly one reviewed Stack rendering.

func NewBootstrapAuthority 

func NewBootstrapAuthority(rendered Rendered, namespaceUID ObservedUID) (BootstrapAuthority, error)

NewBootstrapAuthority creates a private bootstrap capability for one reviewed rendering.

func ReadBootstrapAuthority 

func ReadBootstrapAuthority(path string) (BootstrapAuthority, error)

ReadBootstrapAuthority loads only a private mode-0600 bootstrap capability file.

func (BootstrapAuthority) NonceDigest 

func (authority BootstrapAuthority) NonceDigest() string

NonceDigest is the public Namespace binding for the private bootstrap nonce.

type CatalogEntry 

type CatalogEntry struct {
	// ID is the stable stack-local resource identity.
	ID ResourceID `json:"id"`
	// Kind is the closed typed resource kind.
	Kind ResourceKind `json:"kind"`
	// Owner names the responsible operator role.
	Owner string `json:"owner"`
	// Scope is the declared authority boundary.
	Scope Scope `json:"scope"`
	// Dependencies is canonical dependency order.
	Dependencies []ResourceID `json:"dependencies"`
	// Retention is the explicit lifecycle policy.
	Retention Retention `json:"retention"`
	// BackupRestoreOwner names the responsible recovery role.
	BackupRestoreOwner string `json:"backup_restore_owner"`
	// DeleteBehavior is the containment-safe removal policy.
	DeleteBehavior DeleteBehavior `json:"delete_behavior"`
	// ExternalController states whether another declared controller creates it.
	ExternalController bool `json:"external_controller"`
	// Digest binds this entry to its complete canonical resource declaration.
	Digest string `json:"digest"`
}

CatalogEntry is canonical ownership and provenance metadata for one resource.

type Change 

type Change struct {
	// Resource is the affected stable resource identity.
	Resource ResourceID `json:"resource"`
	// Kind classifies the difference.
	Kind ChangeKind `json:"kind"`
}

Change is one bounded resource-level desired-state difference.

type ChangeKind 

type ChangeKind string

ChangeKind classifies desired-state catalog drift. 

const (
	// ChangeAdded means observed desired state declares a new resource.
	ChangeAdded ChangeKind = "added"
	// ChangeModified means the canonical resource declaration changed.
	ChangeModified ChangeKind = "modified"
	// ChangeRemoved means observed desired state omitted an expected resource.
	ChangeRemoved ChangeKind = "removed"
)

type ComputeResources 

type ComputeResources struct {
	// RequestMilliCPU is the requested CPU in millicores.
	RequestMilliCPU int `json:"request_milli_cpu"`
	// LimitMilliCPU is the finite CPU limit in millicores.
	LimitMilliCPU int `json:"limit_milli_cpu"`
	// RequestMemoryBytes is requested memory in bytes.
	RequestMemoryBytes int64 `json:"request_memory_bytes"`
	// LimitMemoryBytes is the finite memory limit in bytes.
	LimitMemoryBytes int64 `json:"limit_memory_bytes"`
}

ComputeResources declares finite requests and limits.

type ConfigMapMount 

type ConfigMapMount struct {
	// ConfigMap names the Stack ConfigMap resource.
	ConfigMap ResourceID `json:"config_map"`
	// Key names the reviewed ConfigMap key to project.
	Key string `json:"key"`
	// Path is the absolute in-container file path for the projected key.
	Path string `json:"path"`
}

ConfigMapMount binds one reviewed ConfigMap key read-only at an absolute path.

type DatabaseResource 

type DatabaseResource struct {
	// Database is the explicit database name.
	Database string `json:"database"`
	// Schema is the explicit schema name.
	Schema string `json:"schema"`
	// ConnectionReference names a SecretReference resource.
	ConnectionReference ResourceID `json:"connection_reference"`
	// MigrationTarget names the declared Kubernetes workload that executes reviewed migration artifacts.
	MigrationTarget    ResourceID `json:"migration_target"`
	MigrationAuthority string     `json:"migration_authority,omitempty"`
	// Migrations is an ordered reversible migration set.
	Migrations []Migration `json:"migrations"`
}

DatabaseResource declares schema ownership and reversible migrations.

type DeclaredProviderAdapter 

type DeclaredProviderAdapter interface {
	// ReconcileDeclared reconciles all declared non-Kubernetes resources and returns their exact IDs.
	ReconcileDeclared(context.Context, OperatorTarget, Rendered, BootstrapAuthority) ([]ResourceID, error)
	// TeardownDeclared applies each declared non-Kubernetes delete behavior before Kubernetes dependencies disappear.
	TeardownDeclared(context.Context, OperatorTarget, Rendered, BootstrapAuthority) ([]ResourceID, error)
}

DeclaredProviderAdapter reconciles every non-Kubernetes resource in one rendered Stack. Returning the complete affected identity set makes omission and accidental provider authority observable.

type DeleteBehavior 

type DeleteBehavior string

DeleteBehavior describes containment-safe removal semantics. 

const (
	// DeleteOwned permits deletion after identity, labels, and observed UID agree.
	DeleteOwned DeleteBehavior = "delete"
	// DeleteTombstone retains a tombstone after content cleanup.
	DeleteTombstone DeleteBehavior = "tombstone"
	// DeleteRetain leaves the resource under its declared owner.
	DeleteRetain DeleteBehavior = "retain"
)

type Difference 

type Difference struct {
	// Changes is empty only when desired states match.
	Changes []Change `json:"changes"`
}

Difference contains deterministic ResourceID-ordered drift.

func Diff 

func Diff(expected Rendered, candidate io.Reader) (Difference, error)

Diff verifies candidate provenance and returns resource-level desired-state drift.

type EnvironmentVariable 

type EnvironmentVariable struct {
	// Name is the environment key.
	Name string `json:"name"`
	// Value is the bounded non-secret literal value.
	Value string `json:"value"`
}

EnvironmentVariable is one reviewed non-secret workload environment value.

type HostProbe 

type HostProbe interface {
	// Executable reports whether a named command is available.
	Executable(context.Context, string) (bool, error)
	// KubernetesContext returns the selected context without changing it.
	KubernetesContext(context.Context, OperatorTarget) (string, error)
	// Architecture returns the relevant host/runtime architecture.
	Architecture(context.Context) (string, error)
	// FreeDiskBytes returns currently available disk bytes.
	FreeDiskBytes(context.Context) (int64, error)
}

HostProbe exposes only read operations and cannot mutate credentials or context.

type IngressRule 

type IngressRule struct {
	// Host is the reviewed DNS host, or localhost for local development only.
	Host string `json:"host"`
	// Path is the absolute HTTP path.
	Path string `json:"path"`
	// PathType is Exact or Prefix.
	PathType string `json:"path_type"`
	// Service names the Stack Service resource.
	Service ResourceID `json:"service"`
	// ServicePort is the named Service port.
	ServicePort string `json:"service_port"`
}

IngressRule is one bounded route to a declared namespaced Service port.

type JSONLineAuditLog 

type JSONLineAuditLog struct {
	// Path is the caller-supplied audit destination.
	Path string
}

JSONLineAuditLog retains secret-safe operator evidence in an explicit append-only file.

func (JSONLineAuditLog) Append 

func (log JSONLineAuditLog) Append(ctx context.Context, record OperatorAuditRecord) error

Append writes and syncs exactly one JSON operator audit record.

type KubectlAdapter 

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

KubectlAdapter applies and observes only an explicit kubeconfig/context target.

func NewKubectlAdapter 

func NewKubectlAdapter(runner KubectlCommandRunner) (KubectlAdapter, error)

NewKubectlAdapter constructs a Kubernetes provider adapter over an injected process seam.

func (KubectlAdapter) Apply 

func (adapter KubectlAdapter) Apply(ctx context.Context, target OperatorTarget, manifests KubernetesManifests, authority BootstrapAuthority) (KubernetesObservation, error)

Apply applies canonical manifests then re-observes provider object identities.

func (KubectlAdapter) ApplyPostMigration 

func (adapter KubectlAdapter) ApplyPostMigration(ctx context.Context, target OperatorTarget, manifests KubernetesManifests, authority BootstrapAuthority) (KubernetesObservation, error)

ApplyPostMigration applies only Stack Jobs explicitly marked for the post-migration phase and waits for their finite completion.

func (KubectlAdapter) BootstrapNamespace 

func (adapter KubectlAdapter) BootstrapNamespace(ctx context.Context, target OperatorTarget, manifests KubernetesManifests, nonceDigest string) (KubernetesNamespaceObservation, error)

BootstrapNamespace atomically creates only an absent rendered Namespace and then re-observes its identity.

func (KubectlAdapter) Diff 

func (adapter KubectlAdapter) Diff(ctx context.Context, target OperatorTarget, manifests KubernetesManifests) (KubernetesDifference, error)

Diff invokes kubectl's live diff operation and returns only bounded declared resource identities.

func (KubectlAdapter) Observe 

func (adapter KubectlAdapter) Observe(ctx context.Context, target OperatorTarget, manifests KubernetesManifests) (KubernetesObservation, error)

Observe reads every expected object UID and containment label without mutation.

func (KubectlAdapter) Rollback 

func (adapter KubectlAdapter) Rollback(ctx context.Context, target OperatorTarget, current Rendered, previous Rendered, authority BootstrapAuthority) error

Rollback executes only declared current migration artifacts newer than the previous rendered state.

func (KubectlAdapter) Teardown 

func (adapter KubectlAdapter) Teardown(ctx context.Context, target OperatorTarget, rendered Rendered, manifests KubernetesManifests, authority BootstrapAuthority) error

Teardown performs a complete identity preflight and rechecks each UID and label immediately before deletion.

func (KubectlAdapter) Upgrade 

func (adapter KubectlAdapter) Upgrade(ctx context.Context, target OperatorTarget, rendered Rendered, authority BootstrapAuthority) error

Upgrade executes digest-verified declared SQL artifacts through the declared database workload.

func (KubectlAdapter) VerifyBootstrapAuthority 

func (adapter KubectlAdapter) VerifyBootstrapAuthority(ctx context.Context, target OperatorTarget, manifests KubernetesManifests, authority BootstrapAuthority) error

VerifyBootstrapAuthority exposes the read-only provider re-observation used before a reviewed-render transition rewrites private capability state.

type KubectlCommandResult 

type KubectlCommandResult struct {
	// Output is bounded combined command output. It is not retained in audit records.
	Output []byte
	// ExitCode is the child process status; zero means success.
	ExitCode int
}

KubectlCommandResult is bounded process output and its exact exit status.

type KubectlCommandRunner 

type KubectlCommandRunner interface {
	// Run executes an argv-only command with bounded captured output.
	Run(context.Context, string, []string, []byte) (KubectlCommandResult, error)
}

KubectlCommandRunner is the sole process boundary used by KubectlAdapter.

type KubectlDeclaredProviderAdapter 

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

KubectlDeclaredProviderAdapter reconciles the complete non-Kubernetes portion of a Stack through explicitly declared in-cluster operator workloads.

func NewKubectlDeclaredProviderAdapter 

func NewKubectlDeclaredProviderAdapter(runner KubectlCommandRunner) (KubectlDeclaredProviderAdapter, error)

NewKubectlDeclaredProviderAdapter constructs the provider-complete adapter.

func (KubectlDeclaredProviderAdapter) ReconcileDeclared 

func (adapter KubectlDeclaredProviderAdapter) ReconcileDeclared(ctx context.Context, target OperatorTarget, rendered Rendered, authority BootstrapAuthority) ([]ResourceID, error)

ReconcileDeclared reconciles or verifies every non-Kubernetes resource.

func (KubectlDeclaredProviderAdapter) TeardownDeclared 

func (adapter KubectlDeclaredProviderAdapter) TeardownDeclared(ctx context.Context, target OperatorTarget, rendered Rendered, authority BootstrapAuthority) ([]ResourceID, error)

TeardownDeclared applies explicit provider delete behavior before Kubernetes dependencies disappear.

type KubernetesBootstrapAuthorityVerifier 

type KubernetesBootstrapAuthorityVerifier interface {
	VerifyBootstrapAuthority(context.Context, OperatorTarget, KubernetesManifests, BootstrapAuthority) error
}

KubernetesBootstrapAuthorityVerifier re-observes the Namespace identity and nonce binding without applying a new rendering.

type KubernetesDifference 

type KubernetesDifference struct {
	// Changes are sorted Stack resource changes. Empty means the provider matches desired manifests.
	Changes []Change
}

KubernetesDifference contains provider-observed bounded manifest drift.

type KubernetesManifest 

type KubernetesManifest struct {
	// Resource is the Stack resource identity, or "namespace" for the profile namespace.
	Resource ResourceID `json:"-"`
	// APIVersion is the exact Kubernetes API version.
	APIVersion string `json:"apiVersion"`
	// Kind is the exact Kubernetes kind.
	Kind string `json:"kind"`
	// Metadata is explicit object identity and containment labels.
	Metadata KubernetesMetadata `json:"metadata"`
	// Spec is the typed resource projection in Kubernetes API JSON form.
	Spec json.RawMessage `json:"spec,omitempty"`
	// Data is the explicit non-secret ConfigMap data projection.
	Data map[string]string `json:"data,omitempty"`
	// Rules is the bounded Role rule projection.
	Rules []kubernetesRoleRule `json:"rules,omitempty"`
	// RoleRef is the RoleBinding reference projection.
	RoleRef *kubernetesRoleReference `json:"roleRef,omitempty"`
	// Subjects is the RoleBinding subject projection.
	Subjects []kubernetesSubject `json:"subjects,omitempty"`
}

KubernetesManifest is one typed Kubernetes object rendered from a Stack resource. Resource is internal rendering provenance and is deliberately not serialized to Kubernetes.

type KubernetesManifests 

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

KubernetesManifests is an immutable, canonical Kubernetes List for one rendered Stack profile.

func RenderKubernetes 

func RenderKubernetes(rendered Rendered) (KubernetesManifests, error)

RenderKubernetes converts typed rendered desired state into canonical typed Kubernetes manifests. It reads no provider, credentials, environment, or clock state.

func (KubernetesManifests) All 

func (manifests KubernetesManifests) All() []KubernetesManifest

All returns copies of the Namespace followed by canonical Stack resource manifests.

func (KubernetesManifests) InitialTiltManifests 

func (manifests KubernetesManifests) InitialTiltManifests() (KubernetesManifests, error)

InitialTiltManifests retains suspended post-migration Jobs so Tilt can substitute/build their images, while Kubernetes guarantees they cannot run.

func (KubernetesManifests) JSON 

func (manifests KubernetesManifests) JSON() []byte

JSON returns a canonical Kubernetes v1/List document accepted by kubectl apply -f -.

func (KubernetesManifests) Namespace 

func (manifests KubernetesManifests) Namespace() KubernetesManifest

Namespace returns a copy of the explicitly rendered profile Namespace manifest.

func (KubernetesManifests) Objects 

func (manifests KubernetesManifests) Objects() []KubernetesManifest

Objects returns copies of Stack resource manifests in canonical ResourceID order.

func (KubernetesManifests) WithoutPostMigration 

func (manifests KubernetesManifests) WithoutPostMigration() (KubernetesManifests, error)

WithoutPostMigration returns the operator's early mutation phase. It omits one-shot Jobs so stackctl never applies their raw development image values.

type KubernetesMetadata 

type KubernetesMetadata struct {
	// Name is the Kubernetes object name.
	Name string `json:"name"`
	// Namespace is empty only for a Namespace object.
	Namespace string `json:"namespace,omitempty"`
	// Labels bind this object to exactly one rendered Stack and profile.
	Labels map[string]string `json:"labels"`
	// Annotations carry reviewed or operation-specific Kubernetes metadata.
	Annotations map[string]string `json:"annotations,omitempty"`
}

KubernetesMetadata is the typed identity and containment label set of one manifest.

type KubernetesMigrationAdapter 

type KubernetesMigrationAdapter interface {
	// Upgrade applies every declared migration artifact for the rendered Stack profile.
	Upgrade(context.Context, OperatorTarget, Rendered, BootstrapAuthority) error
	// Rollback reverts only migrations present in current and absent from previous rendered state.
	Rollback(context.Context, OperatorTarget, Rendered, Rendered, BootstrapAuthority) error
}

KubernetesMigrationAdapter executes only digest-verified, declared migration artifacts.

type KubernetesNamespaceObservation 

type KubernetesNamespaceObservation struct {
	// Namespace is the exact rendered Namespace name.
	Namespace string `json:"namespace"`
	// UID is the provider-assigned immutable object identity.
	UID ObservedUID `json:"uid"`
	// Labels are the complete containment identity re-observed after creation.
	Labels OwnershipLabels `json:"labels"`
	// RenderDigest binds the observation to the canonical Stack profile.
	RenderDigest string `json:"render_digest"`
}

KubernetesNamespaceObservation binds a newly bootstrapped Namespace to reviewed desired state.

type KubernetesObservation 

type KubernetesObservation struct {
	// ObjectIDs are the Stack resource IDs successfully observed in sorted order.
	ObjectIDs []ResourceID
}

KubernetesObservation contains bounded Kubernetes object identities observed by an adapter.

type KubernetesOperator 

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

KubernetesOperator is the only Stack package service that can call a Kubernetes mutation adapter. Construction alone grants no infrastructure authority; callers must supply an explicit request.

func NewKubernetesOperator 

func NewKubernetesOperator(adapter KubernetesOperatorAdapter, audit OperatorAuditSink) (KubernetesOperator, error)

NewKubernetesOperator constructs an audited operator boundary with no ambient target or credentials.

func NewKubernetesOperatorWithOrchestration 

func NewKubernetesOperatorWithOrchestration(adapter KubernetesOperatorAdapter, orchestration OrchestrationAdapter, audit OperatorAuditSink) (KubernetesOperator, error)

NewKubernetesOperatorWithOrchestration constructs an operator with an explicit orchestration control plane.

func NewKubernetesOperatorWithProviders 

func NewKubernetesOperatorWithProviders(adapter KubernetesOperatorAdapter, providers DeclaredProviderAdapter, audit OperatorAuditSink) (KubernetesOperator, error)

NewKubernetesOperatorWithProviders constructs an operator that owns the complete Kubernetes and non-Kubernetes desired-state reconciliation boundary.

func (KubernetesOperator) Apply 

func (operator KubernetesOperator) Apply(ctx context.Context, request OperatorRequest, rendered Rendered) (KubernetesObservation, error)

Apply renders and applies one reviewed Stack profile as an explicit audited operator action.

func (KubernetesOperator) Bootstrap 

func (operator KubernetesOperator) Bootstrap(ctx context.Context, request OperatorRequest, rendered Rendered) (KubernetesNamespaceObservation, error)

Bootstrap atomically creates only the rendered Namespace after proving it is absent. External controllers may then populate exact declared Secret references before Apply.

func (KubernetesOperator) Diff 

func (operator KubernetesOperator) Diff(ctx context.Context, request OperatorRequest, rendered Rendered) (KubernetesDifference, error)

Diff reads provider state and returns bounded drift against one reviewed Stack profile.

func (KubernetesOperator) Observe 

func (operator KubernetesOperator) Observe(ctx context.Context, request OperatorRequest, rendered Rendered) (KubernetesObservation, error)

Observe reads one reviewed Stack profile through the audited operator boundary without mutation.

func (KubernetesOperator) Reconcile 

func (operator KubernetesOperator) Reconcile(ctx context.Context, request OperatorRequest, rendered Rendered) (ReconcileResult, error)

Reconcile observes declared provider drift, then applies only the selected reviewed manifest set.

func (KubernetesOperator) ReconcileProviders 

func (operator KubernetesOperator) ReconcileProviders(ctx context.Context, request OperatorRequest, rendered Rendered) (ReconcileResult, error)

ReconcileProviders verifies every declared non-Kubernetes provider without diffing Kubernetes fields that a separate declared controller owns. It is an explicit operator action for topologies such as local Tilt where the controller replaces only development image references after rendering.

func (KubernetesOperator) Rollback 

func (operator KubernetesOperator) Rollback(ctx context.Context, request OperatorRequest, current, previous Rendered) (KubernetesObservation, error)

Rollback applies a separately rendered previous Stack state through the same explicit operator boundary.

func (KubernetesOperator) Teardown 

func (operator KubernetesOperator) Teardown(ctx context.Context, request OperatorRequest, rendered Rendered) error

Teardown delegates only containment-safe, re-observed deletion to the explicit operator adapter.

func (KubernetesOperator) Transition 

func (operator KubernetesOperator) Transition(ctx context.Context, request OperatorRequest, current, next Rendered, bind func(BootstrapAuthority) error) error

Transition verifies existing authority against the current reviewed render and binds it to one later render with the same Stack identity. bind is called only after the provider UID/nonce check succeeds.

type KubernetesOperatorAdapter 

type KubernetesOperatorAdapter interface {
	// BootstrapNamespace atomically creates only an absent rendered Namespace and re-observes its identity.
	BootstrapNamespace(context.Context, OperatorTarget, KubernetesManifests, string) (KubernetesNamespaceObservation, error)
	// Apply applies one canonical manifest set and returns its re-observed identities.
	Apply(context.Context, OperatorTarget, KubernetesManifests, BootstrapAuthority) (KubernetesObservation, error)
	// Observe reads the concrete provider objects for one canonical manifest set.
	Observe(context.Context, OperatorTarget, KubernetesManifests) (KubernetesObservation, error)
	// Diff reads provider state and returns only bounded resource-level changes.
	Diff(context.Context, OperatorTarget, KubernetesManifests) (KubernetesDifference, error)
	// Teardown re-observes UID and labels before any containment-safe deletion.
	Teardown(context.Context, OperatorTarget, Rendered, KubernetesManifests, BootstrapAuthority) error
}

KubernetesOperatorAdapter performs provider effects only when explicitly called by KubernetesOperator.

type KubernetesPostMigrationAdapter 

type KubernetesPostMigrationAdapter interface {
	ApplyPostMigration(context.Context, OperatorTarget, KubernetesManifests, BootstrapAuthority) (KubernetesObservation, error)
}

KubernetesPostMigrationAdapter applies the explicitly marked one-shot Jobs only after a successful migration phase.

type KubernetesResource 

type KubernetesResource struct {
	// APIVersion is the pinned Kubernetes API version.
	APIVersion string `json:"api_version"`
	// Kind is the allowlisted Kubernetes kind.
	Kind string `json:"kind"`
	// Name is the DNS-label-safe object name.
	Name string `json:"name"`
	// Replicas is the finite desired count for a Deployment or StatefulSet.
	// Omission in Stack schema v1 resolves to one replica for compatibility.
	Replicas int `json:"replicas,omitempty"`
	// Image is an immutable digest-qualified reference for workloads.
	Image string `json:"image,omitempty"`
	// ServiceAccount names the least-privilege account used by a workload or binding.
	ServiceAccount string `json:"service_account,omitempty"`
	// Role names the Role selected by a RoleBinding.
	Role string `json:"role,omitempty"`
	// Selector names the workload selected by a Service or Ingress backend.
	Selector ResourceID `json:"selector,omitempty"`
	// Command replaces a workload image entrypoint with reviewed argv.
	Command []string `json:"command,omitempty"`
	// Arguments are reviewed argv values passed to Command or the image entrypoint.
	Arguments []string `json:"arguments,omitempty"`
	// Environment contains reviewed non-secret workload environment values.
	Environment []EnvironmentVariable `json:"environment,omitempty"`
	// SecretEnvironment binds named environment values to declared Secret references.
	// It contains references only; secret material never appears in Stack desired state.
	SecretEnvironment []SecretEnvironmentVariable `json:"secret_environment,omitempty"`
	// VolumeMounts binds a workload to explicitly declared PersistentVolumeClaims.
	VolumeMounts []PersistentVolumeMount `json:"volume_mounts,omitempty"`
	// ConfigMapMounts binds reviewed ConfigMap keys read-only into a workload.
	ConfigMapMounts []ConfigMapMount `json:"config_map_mounts,omitempty"`
	// SecretMounts binds reviewed Secret keys read-only into a workload.
	SecretMounts []SecretMount `json:"secret_mounts,omitempty"`
	// Readiness is the explicit workload health probe when an operator must await service readiness.
	Readiness *ReadinessProbe `json:"readiness,omitempty"`
	// PostMigration defers a one-shot Job until every declared database migration
	// has completed. It is only valid for local/CI bootstrap Jobs.
	PostMigration bool `json:"post_migration,omitempty"`
	// Suspend keeps a Job inert while an external development image controller
	// substitutes and builds its image. Post-migration Jobs must start suspended.
	Suspend bool `json:"suspend,omitempty"`
	// Ports is explicit, including an empty array for workloads with no ports.
	Ports []Port `json:"ports,omitempty"`
	// Compute contains finite requests and limits for workloads.
	Compute *ComputeResources `json:"compute,omitempty"`
	// Storage is explicit, including an empty array when no storage is used.
	Storage []Storage `json:"storage,omitempty"`
	// Network contains the NetworkPolicy rule set.
	Network *NetworkRules `json:"network,omitempty"`
	// Permissions contains allowlisted Role permissions.
	Permissions []Permission `json:"permissions,omitempty"`
	// Data contains reviewed non-secret ConfigMap values.
	Data map[string]string `json:"data,omitempty"`
	// IngressRules are explicit HTTP routes owned by a networking.k8s.io/v1 Ingress.
	IngressRules []IngressRule `json:"ingress_rules,omitempty"`
}

KubernetesResource is a typed namespaced Kubernetes desired object.

type Migration 

type Migration struct {
	// Version is a positive monotonically increasing schema version.
	Version int `json:"version"`
	// UpgradeDigest is the immutable upgrade artifact SHA-256.
	UpgradeDigest string `json:"upgrade_digest"`
	// RollbackDigest is the immutable rollback artifact SHA-256.
	RollbackDigest string `json:"rollback_digest"`
	// UpgradeArtifact is the reviewed relative path beneath the explicit operator migration root.
	UpgradeArtifact string `json:"upgrade_artifact"`
	// RollbackArtifact is the reviewed relative path beneath the explicit operator migration root.
	RollbackArtifact string `json:"rollback_artifact"`
}

Migration is a reviewed upgrade and rollback artifact pair.

type Name 

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

Name is the sole validated identity shared by render, apply, and teardown.

func (Name) String 

func (name Name) String() string

String returns the DNS-label-safe stack identity.

type NetworkRules 

type NetworkRules struct {
	// DefaultDeny must be true for an admitted profile.
	DefaultDeny bool `json:"default_deny"`
	// Subject selects the declared workload restricted by this policy; empty selects the namespace.
	Subject ResourceID `json:"subject,omitempty"`
	// AllowDNS permits only UDP and TCP port 53 to kube-system CoreDNS pods.
	AllowDNS bool `json:"allow_dns,omitempty"`
	// AllowedEgress names explicit service resource dependencies.
	AllowedEgress []ResourceID `json:"allowed_egress"`
	// AllowedIngress names the declared workloads permitted to initiate traffic to Subject.
	// An explicitly empty list applies an ingress default-deny policy.
	AllowedIngress []ResourceID `json:"allowed_ingress,omitempty"`
}

NetworkRules declares default-deny policy and bounded exceptions.

type ObservedResource 

type ObservedResource struct {
	// ID is the desired resource identity.
	ID ResourceID `json:"id"`
	// UID is the current provider-observed object identity.
	UID ObservedUID `json:"uid"`
	// Labels are re-read from the target before teardown.
	Labels OwnershipLabels `json:"labels"`
}

ObservedResource is provider-observed identity and labels, never trusted state alone.

type ObservedState 

type ObservedState struct {
	// Stack is the observed Stack identity.
	Stack string `json:"stack"`
	// Profile is the observed profile.
	Profile Profile `json:"profile"`
	// Namespace is the observed explicit namespace.
	Namespace string `json:"namespace"`
	// NamespaceUID is the provider-observed namespace identity.
	NamespaceUID ObservedUID `json:"namespace_uid"`
	// RenderDigest binds observation to reviewed desired state.
	RenderDigest string `json:"render_digest"`
	// Labels are provider-observed namespace ownership labels.
	Labels OwnershipLabels `json:"labels"`
	// Resources is the complete provider-observed owned-resource set.
	Resources []ObservedResource `json:"resources"`
}

ObservedState is the audited operator observation required for safe teardown.

type ObservedUID 

type ObservedUID string

ObservedUID is an opaque provider identity captured during audited apply/observe.

type OperatorAction 

type OperatorAction string

OperatorAction identifies one separately authorized infrastructure operation. 

const (
	// OperatorActionBootstrap atomically creates and records only an absent rendered Namespace.
	OperatorActionBootstrap OperatorAction = "bootstrap"
	// OperatorActionApply applies reviewed Kubernetes manifests.
	OperatorActionApply OperatorAction = "apply"
	// OperatorActionTransition binds Namespace authority to a later reviewed rendering.
	OperatorActionTransition OperatorAction = "transition"
	// OperatorActionObserve reads provider identity without mutation.
	OperatorActionObserve OperatorAction = "observe"
	// OperatorActionDiff compares provider state with reviewed manifests.
	OperatorActionDiff OperatorAction = "diff"
	// OperatorActionReconcile applies only after observing bounded drift.
	OperatorActionReconcile OperatorAction = "reconcile"
	// OperatorActionRollback restores a separately rendered previous Stack state.
	OperatorActionRollback OperatorAction = "rollback"
	// OperatorActionTeardown deletes only after containment verification.
	OperatorActionTeardown OperatorAction = "teardown"
)

type OperatorAuditRecord 

type OperatorAuditRecord struct {
	// Action is the explicit operator operation.
	Action OperatorAction `json:"action"`
	// Actor is the supplied operator identity.
	Actor string `json:"actor"`
	// Context identifies the explicit Kubernetes target, without recording credential material.
	Context string `json:"context"`
	// Stack is the reviewed Stack identity.
	Stack string `json:"stack"`
	// Profile is the reviewed Stack profile.
	Profile Profile `json:"profile"`
	// Digest is the immutable rendered desired-state digest.
	Digest string `json:"digest"`
	// TransitionFromDigest records the reviewed source revision of an explicit rollback.
	// It is empty for non-transition actions.
	TransitionFromDigest string `json:"transition_from_digest,omitempty"`
	// Result is applied, unchanged, observed, differed, rolled_back, torn_down, or failed.
	Result string `json:"result"`
	// Resources is a bounded sorted affected resource identity list.
	Resources []ResourceID `json:"resources,omitempty"`
	// NamespaceUID is retained only for bootstrap, proving which new Namespace was created.
	NamespaceUID ObservedUID `json:"namespace_uid,omitempty"`
	// NamespaceLabels are retained only for bootstrap and bind its containment identity.
	NamespaceLabels *OwnershipLabels `json:"namespace_labels,omitempty"`
}

OperatorAuditRecord is a secret-safe retained record of a requested operator action.

type OperatorAuditSink 

type OperatorAuditSink interface {
	// Append durably records one secret-safe operator result.
	Append(context.Context, OperatorAuditRecord) error
}

OperatorAuditSink retains each operator result outside runtime startup.

type OperatorRequest 

type OperatorRequest struct {
	// Actor is the bounded authenticated operator identity retained in the audit record.
	Actor string
	// Target is the explicit credentials and Kubernetes context boundary.
	Target OperatorTarget
	// BootstrapAuthority is the explicit, identity-bound authority established by bootstrap.
	// Every mutating lifecycle action must present it; it is re-observed at the provider.
	BootstrapAuthority BootstrapAuthority
}

OperatorRequest identifies the human or automation actor and exact infrastructure target.

type OperatorTarget 

type OperatorTarget struct {
	// Kubeconfig is an absolute, caller-supplied configuration path. It is never inferred from the environment.
	Kubeconfig string
	// Context is an explicit context selected from Kubeconfig. It is never inferred from current-context.
	Context string
	// MigrationRoot is the absolute, caller-supplied root containing reviewed migration artifacts.
	MigrationRoot string
}

OperatorTarget pins operator authority to an explicit client configuration and Kubernetes context.

type OrchestrationAdapter 

type OrchestrationAdapter interface {
	ReconcileOrchestration(context.Context, OperatorTarget, Rendered, BootstrapAuthority) ([]ResourceID, error)
}

OrchestrationAdapter reconciles only reviewed durable orchestration declarations.

type OrchestrationResource 

type OrchestrationResource struct {
	// Namespace is the explicit durable orchestration namespace.
	Namespace string `json:"namespace"`
	// TaskQueuePrefix confines durable worker routing to this Stack profile.
	TaskQueuePrefix string `json:"task_queue_prefix"`
	// RetentionDays is finite namespace history retention.
	RetentionDays int `json:"retention_days"`
	// SearchAttributes is the complete typed search-attribute set.
	SearchAttributes []SearchAttribute `json:"search_attributes"`
	// Schedules is the complete declared schedule set.
	Schedules []Schedule `json:"schedules"`
}

OrchestrationResource declares namespace, search attributes, schedules, and retention.

type OwnershipLabels 

type OwnershipLabels struct {
	// PartOf must equal agent-runtime.
	PartOf string `json:"app.kubernetes.io/part-of"`
	// Stack is the sole validated Stack identity.
	Stack string `json:"agent-runtime.dev/stack"`
	// Profile is the rendered profile.
	Profile Profile `json:"agent-runtime.dev/profile"`
}

OwnershipLabels are the exact containment labels attached to owned resources.

type Permission 

type Permission struct {
	// APIGroup is explicit; core is represented by an empty string.
	APIGroup string `json:"api_group"`
	// Resource is one non-wildcard Kubernetes resource name.
	Resource string `json:"resource"`
	// Verbs contains non-wildcard allowed actions.
	Verbs []string `json:"verbs"`
}

Permission is one non-wildcard Kubernetes Role rule.

type PersistentVolumeMount 

type PersistentVolumeMount struct {
	// Claim names the Stack PersistentVolumeClaim resource.
	Claim ResourceID `json:"claim"`
	// Path is the absolute in-container mount path.
	Path string `json:"path"`
	// ReadOnly controls write authority inside the workload.
	ReadOnly bool `json:"read_only"`
}

PersistentVolumeMount binds a workload mount path to a declared PVC resource.

type Port 

type Port struct {
	// Name is stable within the resource.
	Name string `json:"name"`
	// Number is a valid TCP/UDP port.
	Number int `json:"number"`
	// Protocol is TCP or UDP.
	Protocol string `json:"protocol"`
}

Port is one explicitly declared service or container port.

type PreflightReport 

type PreflightReport struct {
	// Results preserves declaration order for operator diagnostics.
	Results []PrerequisiteResult `json:"results"`
}

PreflightReport is the complete read-only result for one profile.

func Preflight 

func Preflight(ctx context.Context, spec Spec, profile Profile, target OperatorTarget, probe HostProbe) (PreflightReport, error)

Preflight checks declared prerequisites without applying any repair or host mutation.

func (PreflightReport) Passed 

func (report PreflightReport) Passed() bool

Passed reports whether every declared prerequisite passed.

type Prerequisite 

type Prerequisite struct {
	// Name is stable within the selected profile.
	Name string `json:"name"`
	// Kind selects the read-only probe operation.
	Kind PrerequisiteKind `json:"kind"`
	// Expected is the required exact value for non-numeric checks.
	Expected string `json:"expected"`
	// MinimumBytes is the finite threshold for free-disk checks.
	MinimumBytes int64 `json:"minimum_bytes"`
	// Repair tells an operator how to fix failure without automatic mutation.
	Repair string `json:"repair"`
}

Prerequisite is one explicit read-only capability check and direct repair.

type PrerequisiteKind 

type PrerequisiteKind string

PrerequisiteKind selects one read-only host capability probe. 

const (
	// PrerequisiteExecutable checks whether a named executable is available.
	PrerequisiteExecutable PrerequisiteKind = "executable"
	// PrerequisiteKubernetesContext checks the selected context without changing it.
	PrerequisiteKubernetesContext PrerequisiteKind = "kubernetes_context"
	// PrerequisiteArchitecture checks the host/runtime architecture.
	PrerequisiteArchitecture PrerequisiteKind = "architecture"
	// PrerequisiteFreeDisk checks available disk against a finite minimum.
	PrerequisiteFreeDisk PrerequisiteKind = "free_disk"
)

type PrerequisiteResult 

type PrerequisiteResult struct {
	// Name identifies the declared prerequisite.
	Name string `json:"name"`
	// Passed is true only when the exact declaration is satisfied.
	Passed bool `json:"passed"`
	// Repair is present only on failure.
	Repair string `json:"repair,omitempty"`
}

PrerequisiteResult is a bounded secret-safe check outcome.

type Profile 

type Profile string

Profile selects one reviewed rendering policy. 

const (
	// ProfileLocal selects the isolated disposable developer topology.
	ProfileLocal Profile = "local"
	// ProfileCI selects the isolated disposable continuous-integration topology.
	ProfileCI Profile = "ci"
	// ProfileProduction selects the persistent self-hosted production topology.
	ProfileProduction Profile = "production"
)

type ProfileSpec 

type ProfileSpec struct {
	Namespace          string
	Prerequisites      []Prerequisite
	SandboxQuotaPolicy SandboxQuotaPolicy
	Resources          []Resource
}

ProfileSpec is one explicitly namespaced resource topology.

type Profiles 

type Profiles struct {
	Local      ProfileSpec
	CI         ProfileSpec
	Production ProfileSpec
}

Profiles is the closed set of reviewed topology profiles in one Stack.

type ReadinessProbe 

type ReadinessProbe struct {
	// Command is reviewed argv executed in the workload container.
	Command []string `json:"command"`
	// InitialDelaySeconds is the finite wait before the first probe.
	InitialDelaySeconds int `json:"initial_delay_seconds"`
	// PeriodSeconds is the finite interval between probes.
	PeriodSeconds int `json:"period_seconds"`
	// FailureThreshold is the finite number of failures before the pod is not ready.
	FailureThreshold int `json:"failure_threshold"`
}

ReadinessProbe is a bounded exec health check declared with a workload.

type ReconcileResult 

type ReconcileResult struct {
	// Applied is true only when declared provider drift was reconciled.
	Applied bool
	// Changes is the bounded sorted observed drift considered by reconciliation.
	Changes []Change
}

ReconcileResult describes whether observed drift required an explicit apply action.

type Rendered 

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

Rendered is immutable canonical desired state for one reviewed profile.

func Render 

func Render(spec Spec, profile Profile) (Rendered, error)

Render produces deterministic desired state without reading environment or infrastructure.

func (Rendered) Digest 

func (rendered Rendered) Digest() string

Digest returns the canonical SHA-256 desired-state identity.

func (Rendered) JSON 

func (rendered Rendered) JSON() []byte

JSON returns a copy of canonical rendered desired state.

func (Rendered) Resources 

func (rendered Rendered) Resources() []Resource

Resources returns a deep copy in canonical ResourceID order.

type Resource 

type Resource struct {
	// ID is stable within every profile of one Stack.
	ID ResourceID `json:"id"`
	// Kind selects exactly one typed payload below.
	Kind ResourceKind `json:"kind"`
	// Owner names the operator role accountable for the resource.
	Owner string `json:"owner"`
	// Scope declares the resource authority boundary.
	Scope Scope `json:"scope"`
	// Dependencies names resources that must be reconciled first.
	Dependencies []ResourceID `json:"dependencies"`
	// Retention declares finite or externally governed retention.
	Retention Retention `json:"retention"`
	// BackupRestoreOwner names the role responsible for backup and restore, or "none".
	BackupRestoreOwner string `json:"backup_restore_owner"`
	// DeleteBehavior declares safe delete, tombstone, or retain behavior.
	DeleteBehavior DeleteBehavior `json:"delete_behavior"`
	// ExternalController states whether a separately declared controller creates it.
	ExternalController bool `json:"external_controller"`
	// Kubernetes contains a Kubernetes object declaration when Kind is kubernetes.
	Kubernetes *KubernetesResource `json:"kubernetes,omitempty"`
	// Orchestration contains durable orchestration declarations when Kind is orchestration.
	Orchestration *OrchestrationResource `json:"orchestration,omitempty"`
	// Blob contains object-storage declarations when Kind is blob.
	Blob *BlobResource `json:"blob,omitempty"`
	// Database contains schema and migration declarations when Kind is database.
	Database *DatabaseResource `json:"database,omitempty"`
	// SecretReference contains provider-owned secret identity when Kind is secret_reference.
	SecretReference *SecretReferenceResource `json:"secret_reference,omitempty"`
	// Telemetry contains collector and retention declarations when Kind is telemetry.
	Telemetry *TelemetryResource `json:"telemetry,omitempty"`
}

Resource is a closed tagged union with common ownership and lifecycle metadata.

type ResourceID 

type ResourceID string

ResourceID is a stable stack-local desired-resource identity.

type ResourceKind 

type ResourceKind string

ResourceKind selects exactly one closed typed resource payload. 

const (
	// ResourceKubernetes is a namespaced Kubernetes desired object.
	ResourceKubernetes ResourceKind = "kubernetes"
	// ResourceOrchestration is a durable orchestration namespace declaration.
	ResourceOrchestration ResourceKind = "orchestration"
	// ResourceBlob is an object-storage bucket and prefix declaration.
	ResourceBlob ResourceKind = "blob"
	// ResourceDatabase is a database schema and migration declaration.
	ResourceDatabase ResourceKind = "database"
	// ResourceSecretReference is an external secret reference, never secret material.
	ResourceSecretReference ResourceKind = "secret_reference"
	// ResourceTelemetry is a telemetry collector and retention declaration.
	ResourceTelemetry ResourceKind = "telemetry"
)

type Retention 

type Retention struct {
	// Policy selects who retains the resource.
	Policy RetentionPolicy `json:"policy"`
	// Days is zero only for ephemeral or externally governed retention.
	Days int `json:"days"`
}

Retention is an explicit finite lifecycle declaration.

type RetentionPolicy 

type RetentionPolicy string

RetentionPolicy classifies resource retention without an implicit default. 

const (
	// RetentionEphemeral deletes content with the owned stack.
	RetentionEphemeral RetentionPolicy = "ephemeral"
	// RetentionPersistent retains content for a finite declared number of days.
	RetentionPersistent RetentionPolicy = "persistent"
	// RetentionExternal delegates retention to the named external controller.
	RetentionExternal RetentionPolicy = "external"
)

type SandboxQuotaPolicy 

type SandboxQuotaPolicy struct {
	// Defaults resolves every omitted sandbox limit once at acceptance.
	Defaults SandboxResourceLimits `json:"defaults"`
	// Maximums is the finite profile admission ceiling for every limit.
	Maximums SandboxResourceLimits `json:"maximums"`
}

SandboxQuotaPolicy supplies explicit defaults and ceilings to sandbox core.

type SandboxResourceLimits 

type SandboxResourceLimits struct {
	// MilliCPU is CPU capacity in integer millicores.
	MilliCPU uint32 `json:"milli_cpu"`
	// MemoryBytes is the memory limit in bytes.
	MemoryBytes uint64 `json:"memory_bytes"`
	// RootDiskBytes is root filesystem capacity in bytes.
	RootDiskBytes uint64 `json:"root_disk_bytes"`
	// TmpfsBytes is aggregate tmpfs capacity in bytes.
	TmpfsBytes uint64 `json:"tmpfs_bytes"`
	// PIDs is the task limit.
	PIDs uint32 `json:"pids"`
	// ProcessCount is the process limit.
	ProcessCount uint32 `json:"process_count"`
	// OpenFiles is the open-file limit.
	OpenFiles uint32 `json:"open_files"`
	// Inodes is the inode limit.
	Inodes uint64 `json:"inodes"`
	// Files is the file-count limit.
	Files uint64 `json:"files"`
	// LifetimeSeconds is finite sandbox lifetime in seconds.
	LifetimeSeconds uint64 `json:"lifetime_seconds"`
	// ProducedOutputBytes is total output production before termination.
	ProducedOutputBytes uint64 `json:"produced_output_bytes"`
	// RetainedOutputBytes is bounded retained output per policy.
	RetainedOutputBytes uint64 `json:"retained_output_bytes"`
	// TransferBytes is aggregate portable transfer capacity.
	TransferBytes uint64 `json:"transfer_bytes"`
	// NetworkConnections is the concurrent connection limit.
	NetworkConnections uint32 `json:"network_connections"`
	// VolumeBytes is aggregate named-volume capacity.
	VolumeBytes uint64 `json:"volume_bytes"`
	// SnapshotBytes is aggregate snapshot capacity.
	SnapshotBytes uint64 `json:"snapshot_bytes"`
}

SandboxResourceLimits mirrors every public sandbox ResourceLimits dimension with explicit units.

type Schedule 

type Schedule struct {
	// Name is the stable schedule name.
	Name string `json:"name"`
	// Cron is the reviewed schedule expression.
	Cron string `json:"cron"`
}

Schedule is one explicit operator-owned schedule declaration.

type Scope 

type Scope string

Scope identifies the declared authority boundary of a resource. 

const (
	// ScopeNamespace is owned inside the profile's explicit namespace.
	ScopeNamespace Scope = "namespace"
	// ScopeCluster is cluster-scoped and requires an explicit operator owner.
	ScopeCluster Scope = "cluster"
	// ScopeProvider is owned through a declared external provider boundary.
	ScopeProvider Scope = "provider"
)

type SearchAttribute 

type SearchAttribute struct {
	// Name is the stable field name.
	Name string `json:"name"`
	// Type is the provider-supported scalar type.
	Type string `json:"type"`
}

SearchAttribute is one durable indexed field declaration.

type SecretEnvironmentVariable 

type SecretEnvironmentVariable struct {
	// Name is the process environment variable name.
	Name string `json:"name"`
	// Secret names the Stack SecretReference resource.
	Secret ResourceID `json:"secret"`
	// Key is the declared non-secret key name within Secret.
	Key string `json:"key"`
}

SecretEnvironmentVariable binds one process environment variable to one key in a declared Secret reference.

type SecretMount 

type SecretMount struct {
	Secret ResourceID `json:"secret"`
	Key    string     `json:"key"`
	Path   string     `json:"path"`
}

SecretMount binds one reviewed Secret key read-only at an absolute path.

type SecretReferenceResource 

type SecretReferenceResource struct {
	// Provider is the declared external secret authority.
	Provider string `json:"provider"`
	// Reference is the provider-owned secret name, never its value.
	Reference string `json:"reference"`
	// Version pins the reviewed secret schema/version selector.
	Version string `json:"version"`
	// Keys is the reviewed non-secret key-name inventory. It never contains values.
	Keys []string `json:"keys,omitempty"`
}

SecretReferenceResource declares only external secret identity and version.

type Spec 

type Spec struct {
	Version int
	Name    Name
	// contains filtered or unexported fields
}

Spec is validated versioned desired state and has no usable zero value.

func Parse 

func Parse(input io.Reader) (Spec, error)

Parse decodes exactly one strict Stack document and validates its identity.

func (Spec) Namespace 

func (spec Spec) Namespace(profile Profile) string

Namespace returns the explicit namespace for a reviewed profile.

func (Spec) SandboxQuotaPolicy 

func (spec Spec) SandboxQuotaPolicy(profile Profile) (SandboxQuotaPolicy, error)

SandboxQuotaPolicy returns the explicit finite sandbox defaults and ceilings for a profile.

func (Spec) StaticAgentSpecBackfill 

func (spec Spec) StaticAgentSpecBackfill() (StaticAgentSpecBackfillV1, bool)

StaticAgentSpecBackfill returns the optional static control-plane declaration without rendering or applying it.

type StaticAgentSpecBackfillAdmission 

type StaticAgentSpecBackfillAdmission struct {
	PolicyDigest  string `json:"policy_digest"`
	BindingDigest string `json:"binding_digest"`
}

StaticAgentSpecBackfillAdmission pins the static validating admission policy and its binding.

type StaticAgentSpecBackfillArchiveIdentity 

type StaticAgentSpecBackfillArchiveIdentity struct {
	Name                      string                          `json:"name"`
	CredentialReferenceDigest string                          `json:"credential_reference_digest"`
	RBACDigest                string                          `json:"rbac_digest"`
	ArchivePolicyDigest       string                          `json:"archive_policy_digest"`
	Identity                  StaticAgentSpecBackfillIdentity `json:"identity"`
}

StaticAgentSpecBackfillArchiveIdentity declares the retained-evidence export authority.

type StaticAgentSpecBackfillClusterOwnership 

type StaticAgentSpecBackfillClusterOwnership struct {
	Owner           string `json:"owner"`
	AuthorityDigest string `json:"authority_digest"`
}

StaticAgentSpecBackfillClusterOwnership identifies a declared cluster-scoped authority without choosing one.

type StaticAgentSpecBackfillController 

type StaticAgentSpecBackfillController struct {
	// Image is an immutable digest-qualified controller image reference.
	Image string `json:"image"`
	// Command is the reviewed executable argv prefix.
	Command []string `json:"command"`
	// Arguments is the reviewed controller argv suffix.
	Arguments []string `json:"arguments"`
	// ConfigDigest pins the bounded controller configuration without embedding it.
	ConfigDigest string `json:"config_digest"`
	// Resources bounds controller CPU and memory.
	Resources *ComputeResources `json:"resources"`
}

StaticAgentSpecBackfillController is the immutable controller workload declaration.

type StaticAgentSpecBackfillCredentials 

type StaticAgentSpecBackfillCredentials struct {
	ControllerReferenceDigest    string `json:"controller_reference_digest"`
	DatabaseReadCapabilityDigest string `json:"database_read_capability_digest"`
	BlobReadCapabilityDigest     string `json:"blob_read_capability_digest"`
}

StaticAgentSpecBackfillCredentials pins non-secret external credential/capability declarations.

type StaticAgentSpecBackfillIdentities 

type StaticAgentSpecBackfillIdentities struct {
	Namespace                string `json:"namespace"`
	ControllerServiceAccount string `json:"controller_service_account"`
	ControllerRole           string `json:"controller_role"`
	ControllerRoleBinding    string `json:"controller_role_binding"`
	OperatorServiceAccount   string `json:"operator_service_account"`
	OperatorRole             string `json:"operator_role"`
	OperatorRoleBinding      string `json:"operator_role_binding"`
}

StaticAgentSpecBackfillIdentities is the exact namespaced controller/operator identity set.

type StaticAgentSpecBackfillIdentity 

type StaticAgentSpecBackfillIdentity struct {
	SubjectKind               string       `json:"subject_kind"`
	Subject                   string       `json:"subject"`
	Namespace                 string       `json:"namespace"`
	CredentialReferenceDigest string       `json:"credential_reference_digest"`
	RBACDigest                string       `json:"rbac_digest"`
	Permissions               []Permission `json:"permissions"`
}

StaticAgentSpecBackfillIdentity declares one explicit Kubernetes or external identity and narrow rules.

type StaticAgentSpecBackfillInventory 

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

StaticAgentSpecBackfillInventory is immutable canonical static control-plane desired state. It is deliberately non-applicable; a separately authorized future operator must consume it.

func CompileStaticAgentSpecBackfillInventory 

func CompileStaticAgentSpecBackfillInventory(spec Spec) (StaticAgentSpecBackfillInventory, error)

CompileStaticAgentSpecBackfillInventory compiles declared static control-plane facts without provider effects.

func (StaticAgentSpecBackfillInventory) Digest 

func (inventory StaticAgentSpecBackfillInventory) Digest() string

Digest returns the canonical SHA-256 identity of the non-applying static inventory.

func (StaticAgentSpecBackfillInventory) JSON 

func (inventory StaticAgentSpecBackfillInventory) JSON() []byte

JSON returns a copy of the canonical non-applying static inventory.

type StaticAgentSpecBackfillInventoryV1 

type StaticAgentSpecBackfillInventoryV1 struct {
	// Profile binds the inventory to one reviewed Stack profile.
	Profile Profile `json:"profile"`
	// ClusterOwnership identifies the separately declared owner of cluster-scoped static resources.
	ClusterOwnership StaticAgentSpecBackfillClusterOwnership `json:"cluster_ownership"`
	// ControllerIdentity declares the controller subject, reference, and least-privilege rules.
	ControllerIdentity StaticAgentSpecBackfillIdentity `json:"controller_identity"`
	// OperatorIdentity declares the request-creator subject, reference, and least-privilege rules.
	OperatorIdentity StaticAgentSpecBackfillIdentity `json:"operator_identity"`
	// LifecycleIdentity declares the distinct read-only readiness observer.
	LifecycleIdentity StaticAgentSpecBackfillLifecycleIdentity `json:"lifecycle_identity"`
	// ArchiveIdentity declares the distinct retained-evidence exporter.
	ArchiveIdentity StaticAgentSpecBackfillArchiveIdentity `json:"archive_identity"`
	// Admission pins the static validating policy and binding that fence request mutation authority.
	Admission StaticAgentSpecBackfillAdmission `json:"admission"`
	// RuntimeTarget declares the runtime namespace and an explicit later UID-bound ingress handoff.
	RuntimeTarget StaticAgentSpecBackfillRuntimeTarget `json:"runtime_target"`
}

StaticAgentSpecBackfillInventoryV1 names the explicit authority facts for one non-applying static inventory. It deliberately declares rather than infers profile, cluster ownership, identities, routes, and UID handoff.

type StaticAgentSpecBackfillLifecycleIdentity 

type StaticAgentSpecBackfillLifecycleIdentity struct {
	Name                       string                          `json:"name"`
	CredentialReferenceDigest  string                          `json:"credential_reference_digest"`
	RBACDigest                 string                          `json:"rbac_digest"`
	ObservationAuthorityDigest string                          `json:"observation_authority_digest"`
	Identity                   StaticAgentSpecBackfillIdentity `json:"identity"`
}

StaticAgentSpecBackfillLifecycleIdentity declares the static readiness observer's distinct authority.

type StaticAgentSpecBackfillPlan 

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

StaticAgentSpecBackfillPlan is immutable canonical desired state for a control plane that is deliberately not applied.

func RenderStaticAgentSpecBackfill 

func RenderStaticAgentSpecBackfill(spec Spec) (StaticAgentSpecBackfillPlan, error)

RenderStaticAgentSpecBackfill compiles one declared static control plane into canonical non-applicable desired state.

func (StaticAgentSpecBackfillPlan) Digest 

func (plan StaticAgentSpecBackfillPlan) Digest() string

Digest returns the canonical SHA-256 identity of the render-only control-plane plan.

func (StaticAgentSpecBackfillPlan) JSON 

func (plan StaticAgentSpecBackfillPlan) JSON() []byte

JSON returns a copy of the canonical render-only plan.

type StaticAgentSpecBackfillRBAC 

type StaticAgentSpecBackfillRBAC struct {
	ControllerDigest string `json:"controller_digest"`
	OperatorDigest   string `json:"operator_digest"`
}

StaticAgentSpecBackfillRBAC pins static Kubernetes RBAC declarations without embedding rules.

type StaticAgentSpecBackfillRoute 

type StaticAgentSpecBackfillRoute struct {
	Kind            string `json:"kind"`
	Namespace       string `json:"namespace"`
	Service         string `json:"service"`
	PortName        string `json:"port_name"`
	PortNumber      int    `json:"port_number"`
	Protocol        string `json:"protocol"`
	AuthorityDigest string `json:"authority_digest"`
}

StaticAgentSpecBackfillRoute is one exact named service egress authority.

type StaticAgentSpecBackfillRuntimeTarget 

type StaticAgentSpecBackfillRuntimeTarget struct {
	Namespace           string `json:"namespace"`
	TargetIngressDigest string `json:"target_ingress_digest"`
	UIDHandshakeDigest  string `json:"uid_handshake_digest"`
}

StaticAgentSpecBackfillRuntimeTarget declares a target namespace and the not-yet-realized UID-bound ingress handoff.

type StaticAgentSpecBackfillV1 

type StaticAgentSpecBackfillV1 struct {
	// Version is the sole supported declaration version.
	Version int `json:"version"`
	// CRDDigest pins the exact generated AgentSpecBackfill CRD declaration.
	CRDDigest string `json:"crd_digest"`
	// Controller pins the controller process image, argv, configuration digest, and finite resources.
	Controller StaticAgentSpecBackfillController `json:"controller"`
	// Identities fixes the only controller and limited-operator Kubernetes identities.
	Identities StaticAgentSpecBackfillIdentities `json:"identities"`
	// Routes is the complete explicit Kubernetes API, database, blob, and optional DNS egress set.
	Routes []StaticAgentSpecBackfillRoute `json:"routes"`
	// RBAC pins the reviewed controller and limited-operator role/binding declarations.
	RBAC StaticAgentSpecBackfillRBAC `json:"rbac"`
	// Credentials pins non-secret credential-reference and capability declarations.
	Credentials StaticAgentSpecBackfillCredentials `json:"credentials"`
	// EvidenceRetentionDays is the finite terminal-evidence retention period.
	EvidenceRetentionDays int `json:"evidence_retention_days"`
	// TeardownInventory is the complete static resource inventory for declarative teardown.
	TeardownInventory []string `json:"teardown_inventory"`
	// Inventory supplies every explicit non-secret authority fact required by the static inventory compiler.
	Inventory *StaticAgentSpecBackfillInventoryV1 `json:"inventory,omitempty"`
}

StaticAgentSpecBackfillV1 is the optional, immutable render-only declaration of the static backfill control plane.

type Storage 

type Storage struct {
	// Name is stable within the resource.
	Name string `json:"name"`
	// SizeBytes is the finite requested size.
	SizeBytes int64 `json:"size_bytes"`
	// Class is the explicitly selected storage class or "ephemeral".
	Class string `json:"class"`
}

Storage declares one finite named storage allocation.

type SystemKubectlRunner 

type SystemKubectlRunner struct{}

SystemKubectlRunner is the argv-only production command runner for stackctl.

func (SystemKubectlRunner) Run 

func (SystemKubectlRunner) Run(ctx context.Context, program string, arguments []string, input []byte) (KubectlCommandResult, error)

Run executes one bounded kubectl child process.

type TeardownAction 

type TeardownAction struct {
	// Resource identifies the desired resource.
	Resource ResourceID `json:"resource"`
	// UID is the exact current provider identity that must still match at execution.
	UID ObservedUID `json:"uid"`
	// Behavior selects delete, tombstone, or retain.
	Behavior DeleteBehavior `json:"behavior"`
}

TeardownAction is one identity-bound operator action in safe dependency order.

type TeardownPlan 

type TeardownPlan struct {
	// Stack is the sole Stack identity.
	Stack string `json:"stack"`
	// Profile is the reviewed profile.
	Profile Profile `json:"profile"`
	// Namespace is the explicit owned namespace.
	Namespace string `json:"namespace"`
	// NamespaceUID must still match before namespace deletion.
	NamespaceUID ObservedUID `json:"namespace_uid"`
	// RenderDigest binds every action to reviewed desired state.
	RenderDigest string `json:"render_digest"`
	// Actions are reverse dependency ordered.
	Actions []TeardownAction `json:"actions"`
}

TeardownPlan is immutable input to a separately audited operator adapter.

func PlanKubernetesTeardown 

func PlanKubernetesTeardown(rendered Rendered, observed ObservedState) (TeardownPlan, error)

PlanKubernetesTeardown proves containment for exactly the Kubernetes resources observed by the Kubernetes adapter; provider resources require their own adapter proof.

func PlanTeardown 

func PlanTeardown(rendered Rendered, observed ObservedState) (TeardownPlan, error)

PlanTeardown refuses unproven ownership and returns no mutation capability.

type TelemetryResource 

type TelemetryResource struct {
	// CollectorService names a declared Kubernetes Service dependency.
	CollectorService ResourceID `json:"collector_service"`
	// PortName selects one declared service port by name.
	PortName string `json:"port_name"`
	// RetentionDays is finite telemetry retention.
	RetentionDays int `json:"retention_days"`
}

TelemetryResource declares a collector service and finite retention.

type TemporalCLIAdapter 

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

TemporalCLIAdapter reconciles namespaces through the declared Temporal deployment only.

func NewTemporalCLIAdapter 

func NewTemporalCLIAdapter(runner KubectlCommandRunner) (TemporalCLIAdapter, error)

NewTemporalCLIAdapter constructs a bounded operator-only Temporal CLI adapter.

func (TemporalCLIAdapter) ReconcileOrchestration 

func (adapter TemporalCLIAdapter) ReconcileOrchestration(ctx context.Context, target OperatorTarget, rendered Rendered, authority BootstrapAuthority) ([]ResourceID, error)

ReconcileOrchestration describes then creates each declared namespace idempotently.

func (TemporalCLIAdapter) TeardownOrchestration 

func (adapter TemporalCLIAdapter) TeardownOrchestration(ctx context.Context, target OperatorTarget, rendered Rendered, resourceID ResourceID, authority BootstrapAuthority) error

TeardownOrchestration deletes one explicitly owned namespace only when its rendered resource identity and lifecycle authorize deletion.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.