model

type APIKey struct {
	ID        APIKeyID   `json:"id" yaml:"id"`
	Hash      string     `json:"hash" yaml:"hash"`
	Role      APIKeyRole `json:"role" yaml:"role"`
	Name      string     `json:"name,omitempty" yaml:"name,omitempty"`
	CreatedAt time.Time  `json:"created_at" yaml:"created_at"`
	ExpiresAt *time.Time `json:"expires_at,omitempty" yaml:"expires_at,omitempty"`
	RevokedAt *time.Time `json:"revoked_at,omitempty" yaml:"revoked_at,omitempty"`
	// Kind distinguishes an admin-issued service key from a self-service
	// personal key. Empty on every key created before this field existed
	// and on every key the existing admin-only POST /api/v1/api-keys
	// endpoint creates -- see EffectiveKind.
	Kind APIKeyKind `json:"kind,omitempty" yaml:"kind,omitempty"`
	// Subject identifies the human a personal key was minted for (an
	// "oidc:<sub>" identity, see auth.SessionPrincipal). Empty for
	// service keys, which have no such identity to record.
	Subject string `json:"subject,omitempty" yaml:"subject,omitempty"`
}

type APIKeyID string

type APIKeyKind string

type APIKeyRole string

type AgentIdentity struct {
	AgentID    string    `json:"agent_id" yaml:"agent_id"`
	CertSerial string    `json:"cert_serial" yaml:"cert_serial"`
	IssuedAt   time.Time `json:"issued_at" yaml:"issued_at"`
}

type AgentIdentityID string

type AgentRegistrationToken struct {
	ID        AgentTokenID `json:"id" yaml:"id"`
	TokenHash string       `json:"token_hash" yaml:"token_hash"`
	CreatedAt time.Time    `json:"created_at" yaml:"created_at"`
	ExpiresAt time.Time    `json:"expires_at" yaml:"expires_at"`
	UsedAt    *time.Time   `json:"used_at,omitempty" yaml:"used_at,omitempty"`
	Label     string       `json:"label,omitempty" yaml:"label,omitempty"`
}

type AgentTokenID string

type Execution struct {
	ID                 ExecutionID        `json:"id"`
	SandboxID          SandboxID          `json:"sandbox_id"`
	ResourceID         ResourceID         `json:"resource_id"`
	ActorID            string             `json:"actor_id,omitempty"`
	Status             ExecutionStatus    `json:"status"`
	InputKind          ExecutionInputKind `json:"input_kind"`
	RequestFingerprint string             `json:"request_fingerprint"`
	CreatedAt          time.Time          `json:"created_at"`
	StartedAt          *time.Time         `json:"started_at,omitempty"`
	FinishedAt         *time.Time         `json:"finished_at,omitempty"`
	DeadlineAt         time.Time          `json:"deadline_at"`
	ExitCode           *int               `json:"exit_code,omitempty"`
	Error              string             `json:"error,omitempty"`
	Truncated          bool               `json:"truncated,omitempty"`
	Chunks             []ExecutionChunk   `json:"chunks,omitempty"`
}

type ExecutionChunk struct {
	Cursor  uint64 `json:"cursor"`
	Stream  string `json:"stream"`
	Data    []byte `json:"data"`
	Dropped bool   `json:"dropped,omitempty"`
}

type ExecutionID string

type ExecutionInputKind string

type ExecutionStatus string

type LocalAdminAccount struct {
	Username     string    `json:"username" yaml:"username"`
	PasswordHash string    `json:"password_hash" yaml:"password_hash"`
	CreatedAt    time.Time `json:"created_at" yaml:"created_at"`
}

type Pool struct {
	Name PoolName `json:"name" yaml:"name"`

	// Template is the reusable desired resource shape used by this pool.
	Template string `json:"template,omitempty" yaml:"template,omitempty"`

	// Source and Packages are the resolved resource configuration carried by
	// this pool. They are optional for legacy inline pools.
	Source   string   `json:"source,omitempty" yaml:"source,omitempty"`
	Packages []string `json:"packages,omitempty" yaml:"packages,omitempty"`

	// Policies are pool-level behavioral controls (preheating, limits, etc).
	Policies PoolPolicies `json:"policies,omitempty" yaml:"policies,omitempty"`

	// Drain records desired drain state for unused pool inventory.
	Drain PoolDrainState `json:"drain,omitempty" yaml:"drain,omitempty"`

	// Configuration records where editable policy values came from. Static
	// provider, template, store, and secret definitions remain local-file owned.
	Configuration PoolConfigurationState `json:"configuration,omitempty" yaml:"configuration,omitempty"`

	// Inventory is the current contents of the pool.
	Inventory ResourceCollection `json:"inventory" yaml:"inventory"`
}

type PoolConfigurationState struct {
	Provenance    string    `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	LocalRevision string    `json:"local_revision,omitempty" yaml:"local_revision,omitempty"`
	Pending       bool      `json:"pending,omitempty" yaml:"pending,omitempty"`
	UpdatedAt     time.Time `json:"updated_at,omitempty" yaml:"updated_at,omitempty"`
}

type PoolDebugPolicy struct {
	// RetainFailedResources keeps a resource's VM and rotated guest
	// credential running after admission (personalization or package
	// application) fails, instead of the default power-down-and-remove
	// teardown. A manual Retry against a retained resource re-admits it in
	// place -- reusing the same VM and credential -- rather than destroying
	// and recreating it from the template. Intended only for
	// troubleshooting: a retained failed resource still consumes pool
	// max_total capacity and can make the pool blocked exactly like any
	// other failed resource.
	RetainFailedResources bool `json:"retain_failed_resources,omitempty" yaml:"retain_failed_resources,omitempty"`
}

type PoolDrainState struct {
	// ConfigDeclared is true when config declares the pool drained.
	ConfigDeclared bool `json:"config_declared,omitempty" yaml:"config_declared,omitempty"`

	// Operator is a persisted operator/debug override.
	Operator bool `json:"operator,omitempty" yaml:"operator,omitempty"`
}

type PoolName string

type PoolPolicies struct {
	// Preheat controls keeping resources ready ahead of time.
	Preheat PreheatPolicy `json:"preheat,omitempty" yaml:"preheat,omitempty"`

	// Recycle controls periodic replacement of unused pool inventory.
	//
	// This does NOT mean resources are returned to the pool after sandbox use.
	// Resources remain single-use; recycle applies only to unused inventory.
	Recycle RecyclePolicy `json:"recycle,omitempty" yaml:"recycle,omitempty"`

	// Debug controls operator-opt-in troubleshooting behavior that trades
	// safety/cost for investigability. Debug settings are local-config-owned
	// only, like provider/template/store/secret definitions -- they are not
	// exposed through the pool Save-and-Apply web/API surface.
	Debug PoolDebugPolicy `json:"debug,omitempty" yaml:"debug,omitempty"`
}

type PreheatPolicy struct {
	// MinReady is the number of ready units the pool should try to keep
	// available in the background. It is a soft preheat target, not a
	// second hard admission cap stacked on top of MaxTotal: failing to
	// reach MinReady alone never rejects an allocation request (see
	// #240) -- though a request can still fail for other reasons, e.g. a
	// drained pool or a provisioning error. A live allocation call may
	// still opportunistically top up toward MinReady in the background,
	// so a failure in that best-effort top-up can itself surface as an
	// error even when the request was already satisfiable -- see #249
	// for that residual gap.
	MinReady int `json:"min_ready,omitempty" yaml:"min_ready,omitempty"`

	// MaxTotal is the maximum total units that may exist for the pool.
	MaxTotal int `json:"max_total,omitempty" yaml:"max_total,omitempty"`
}

type Profile struct {
	Type ResourceType    `json:"type" yaml:"type"`
	Name ResourceProfile `json:"name" yaml:"name"`
}

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

type ProviderRef struct {
	Name string `json:"name" yaml:"name"`

	// AgentID is the specific agent instance (embedded or remote) that
	// provisioned this resource, stamped once at creation time. It is
	// deliberately distinct from Name (the provider type/instance): once
	// more than one agent can advertise the same provider type, any
	// lifecycle call on an existing resource (Destroy, Allocate) must
	// route back to this exact agent rather than re-resolving by type,
	// or it risks silently misrouting to a different agent that knows
	// nothing about the resource. See docs/adr/0005-remote-agent-transport-and-registration.md.
	AgentID string `json:"agent_id,omitempty" yaml:"agent_id,omitempty"`
}

type RecyclePolicy struct {
	// MaxAge is an optional upper bound on how long an unused resource may sit in
	// a pool before it should be recycled (destroy + replace).
	// Example values: "30m", "8h", "24h".
	MaxAge string `json:"max_age,omitempty" yaml:"max_age,omitempty"`
}

type Resource struct {
	ID ResourceID `json:"id,omitempty" yaml:"id,omitempty"`

	// Type is intrinsic to the resource, independent of which container holds it.
	Type ResourceType `json:"type,omitempty" yaml:"type,omitempty"`

	// Profile is a Boxy-defined variant identifier for this resource's Type.
	// Example: vm "win-2022", container "ubuntu-2204".
	Profile ResourceProfile `json:"profile,omitempty" yaml:"profile,omitempty"`

	// OriginPool is the immutable pool that originally provisioned this resource.
	// It is used for pool-level capacity accounting even after allocation removes
	// the resource from ready inventory.
	OriginPool PoolName `json:"origin_pool,omitempty" yaml:"origin_pool,omitempty"`

	// CurrentPool is the pool that currently owns this resource for inventory
	// and capacity accounting. Empty on legacy records means OriginPool.
	CurrentPool PoolName `json:"current_pool,omitempty" yaml:"current_pool,omitempty"`

	// PendingPool is set while a resource is being promoted into another pool.
	// It is cleared when promotion succeeds or the resource is quarantined.
	PendingPool PoolName `json:"pending_pool,omitempty" yaml:"pending_pool,omitempty"`

	// Provider identifies the external system instance this resource belongs to.
	Provider ProviderRef `json:"provider" yaml:"provider"`

	State ResourceState `json:"state,omitempty" yaml:"state,omitempty"`

	// Properties holds provider-specific data that Boxy core should not interpret.
	Properties map[string]any `json:"properties,omitempty" yaml:"properties,omitempty"`

	// AppliedPackages records successful resource-package applications. The
	// package engine uses the immutable reference and canonical input digest for
	// idempotency; this is not a guest drift detector.
	AppliedPackages []resourcepack.AppliedPackage `json:"applied_packages,omitempty" yaml:"applied_packages,omitempty"`

	CreatedAt time.Time `json:"created_at,omitempty" yaml:"created_at,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitempty" yaml:"updated_at,omitempty"`
}

type ResourceCollection struct {
	// ExpectedType is a constraint: all Resources must have Resource.Type == ExpectedType.
	ExpectedType ResourceType `json:"expected_type" yaml:"expected_type"`

	// ExpectedProfile is a constraint: all Resources must have Resource.Profile == ExpectedProfile.
	ExpectedProfile ResourceProfile `json:"expected_profile" yaml:"expected_profile"`

	Resources []Resource `json:"resources,omitempty" yaml:"resources,omitempty"`
}

type ResourceID string

type ResourceProfile string

type ResourceRequest struct {
	Type     ResourceType    `json:"type" yaml:"type"`
	Profile  ResourceProfile `json:"profile" yaml:"profile"`
	Count    int             `json:"count" yaml:"count"`
	Packages []string        `json:"packages,omitempty" yaml:"packages,omitempty"`
}

type ResourceState string

type ResourceTemplate struct {
	Name     string         `json:"name" yaml:"name"`
	Extends  string         `json:"extends,omitempty" yaml:"extends,omitempty"`
	Type     string         `json:"type,omitempty" yaml:"type,omitempty"`
	Provider string         `json:"provider,omitempty" yaml:"provider,omitempty"`
	Agent    string         `json:"agent,omitempty" yaml:"agent,omitempty"`
	Source   string         `json:"source,omitempty" yaml:"source,omitempty"`
	Config   map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
	Packages []string       `json:"packages,omitempty" yaml:"packages,omitempty"`
}

type ResourceType string

type RevokedAgentIdentity struct {
	ID         AgentIdentityID `json:"id" yaml:"id"`
	AgentID    string          `json:"agent_id" yaml:"agent_id"`
	CertSerial string          `json:"cert_serial" yaml:"cert_serial"`
	RevokedAt  time.Time       `json:"revoked_at" yaml:"revoked_at"`
	Reason     string          `json:"reason,omitempty" yaml:"reason,omitempty"`
}

type Sandbox struct {
	ID      SandboxID `json:"id" yaml:"id"`
	Name    string    `json:"name,omitempty" yaml:"name,omitempty"`
	OwnerID string    `json:"owner_id,omitempty" yaml:"owner_id,omitempty"`

	// Policies are sandbox-level behavioral controls (security, retention, etc).
	Policies SandboxPolicies `json:"policies,omitzero" yaml:"policies,omitempty"`

	// Status is the async lifecycle state of the sandbox request.
	Status SandboxStatus `json:"status,omitempty" yaml:"status,omitempty"`

	// Requests are the desired resources for this sandbox.
	Requests []ResourceRequest `json:"requests,omitempty" yaml:"requests,omitempty"`

	// Error is a human-readable failure detail when Status=failed.
	Error string `json:"error,omitempty" yaml:"error,omitempty"`

	// Resources are the resources that make up this sandbox.
	Resources []ResourceID `json:"resources,omitempty" yaml:"resources,omitempty"`

	// ExpiresAt is the absolute time this sandbox should be automatically
	// destroyed, computed from Policies.AutoDestroyAfter at creation time.
	// Nil means no automatic expiry.
	ExpiresAt *time.Time `json:"expires_at,omitempty" yaml:"expires_at,omitempty"`
}

type SandboxID string

type SandboxPolicies struct {
	// AutoDestroyAfter is an optional retention setting (e.g. "30m", "8h").
	// Empty means "no policy set here".
	AutoDestroyAfter string `json:"auto_destroy_after,omitempty" yaml:"auto_destroy_after,omitempty"`

	// SecurityProfile is an optional label for sandbox hardening posture.
	// Examples: "default", "lab", "pentest", "vdi".
	SecurityProfile string `json:"security_profile,omitempty" yaml:"security_profile,omitempty"`
}

type SandboxStatus string

type Session struct {
	ID   SessionID   `json:"id" yaml:"id"`
	Hash string      `json:"hash" yaml:"hash"`
	Kind SessionKind `json:"kind" yaml:"kind"`
	// Subject identifies the principal within Kind: the local admin
	// account's username for SessionKindLocalAdmin, or the OIDC subject
	// claim for SessionKindOIDC.
	Subject   string     `json:"subject" yaml:"subject"`
	Role      APIKeyRole `json:"role" yaml:"role"`
	CreatedAt time.Time  `json:"created_at" yaml:"created_at"`
	ExpiresAt time.Time  `json:"expires_at" yaml:"expires_at"`
}

type SessionID string

type SessionKind string