storage

type AgentUpgradeAttempt struct {
	AttemptID                        string
	IdempotencyKey                   string
	Namespace                        string
	WorkspaceName                    string
	WorkspaceUID                     string
	VMUID                            string
	ActorUID                         string
	TargetID                         string
	TargetManifestSHA256             string
	ExpectedInstalledInventorySHA256 string
	ExpectedRevocationEpoch          uint64
	AllowReboot                      bool
	ExecutionID                      string
	RecordingID                      string
	State                            AttemptState
	PhaseTimes                       map[AttemptState]time.Time
	CancelRequested                  bool
	JournalSequence                  uint64
	ErrorCode                        string
	Predecessor                      AttemptPredecessor
	LeaseOwner                       string
	LeaseExpiresAt                   time.Time
	LeaseFence                       uint64
	CreatedAt                        time.Time
	UpdatedAt                        time.Time
}

type AgentUpgradeStore interface {
	// Reserve atomically claims a new attempt. ErrConflict means the attempt
	// id exists, ErrVMReserved means another active attempt holds the VM, and
	// ErrIdempotencyConflict means the key exists with a different request.
	Reserve(ctx context.Context, a AgentUpgradeAttempt) error
	// Get returns the attempt or ErrNotFound.
	Get(ctx context.Context, attemptID string) (AgentUpgradeAttempt, error)
	// GetByIdempotency returns the attempt previously admitted under the key
	// or ErrNotFound.
	GetByIdempotency(ctx context.Context, namespace, workspaceName, key string) (AgentUpgradeAttempt, error)
	// ActiveAttempt returns the reservation-holding attempt for a VM UID or
	// ErrNotFound when the VM is free.
	ActiveAttempt(ctx context.Context, vmUID string) (AgentUpgradeAttempt, error)
	// Transition applies a fenced or administrative state change. It fails
	// with ErrNotFound, ErrConflict (wrong current state), ErrFenced or
	// ErrLeaseExpired.
	Transition(ctx context.Context, attemptID string, from AttemptState, t AttemptTransition) error
	// ClaimLease takes or steals an expired worker lease, returning the new
	// monotonically increasing fence.
	ClaimLease(ctx context.Context, attemptID, owner string, now time.Time, ttl time.Duration) (uint64, error)
	// RenewLease extends a held lease without changing the fence.
	RenewLease(ctx context.Context, attemptID, owner string, fence uint64, now time.Time, ttl time.Duration) error
	// ReleaseLease drops a held lease early, fencing the worker out.
	ReleaseLease(ctx context.Context, attemptID, owner string, fence uint64) error
	// RequestCancel records a safe-cancellation request without changing the
	// attempt state or the held lease. The worker observes the flag and stops
	// at its next safe transaction boundary; it is idempotent.
	RequestCancel(ctx context.Context, attemptID string, now time.Time) error
	Ready(ctx context.Context) error
	Close() error
}

type AttemptPredecessor struct {
	TargetID       string `json:"target_id"`
	ManifestSHA256 string `json:"manifest_sha256"`
}

type AttemptState string

type AttemptTransition struct {
	To              AttemptState
	Now             time.Time
	Fence           *uint64
	ErrorCode       string
	CancelRequested *bool
	JournalSequence *uint64
	Predecessor     *AttemptPredecessor
}

type AuditEvent struct {
	ExecutionID string
	Time        time.Time
	Kind        string
	ActorID     string
	// Detail carries non-sensitive structured context. It must never contain
	// command bodies, stdin, output or terminal content.
	Detail map[string]string
}

type Durability string

type EnrollmentCredential struct {
	TokenHash       string
	Namespace       string
	WorkspaceName   string
	WorkspaceUID    string
	Generation      string
	RevocationEpoch uint64
	ExpiresAt       time.Time
	CSRHash         string
	CertificateDER  []byte
}

type EnrollmentStore interface {
	Create(ctx context.Context, credential EnrollmentCredential) error
	Get(ctx context.Context, tokenHash string) (EnrollmentCredential, error)
	Redeem(ctx context.Context, tokenHash, csrHash string, certificateDER []byte, now time.Time) ([]byte, error)
	Ready(ctx context.Context) error
	Close() error
}

type ExecutionOutcome struct {
	State         State
	StartTime     time.Time
	EndTime       time.Time
	ExitCode      *int
	Termination   string
	RecordingLost bool
}

type ExecutionRecord struct {
	ExecutionID         string
	ActorID             string
	Operation           Operation
	Namespace           string
	WorkspaceName       string
	WorkspaceUID        string
	WorkspaceGeneration int64
	GrantVersion        string
	OSIdentity          string
	Elevated            bool
	RecordingID         string
	Mode                string
	Durability          Durability
	AdmissionTime       time.Time
	Admitted            bool
	DenyReason          string
}

type Filter struct {
	Namespace     string
	WorkspaceName string
	ActorID       string
	Since         time.Time
	Limit         int
}

type FinalizeMeta struct {
	ActorID string
	EndTime time.Time
}

type Manifest struct {
	Authentication string    `json:"authentication"`
	Version        int       `json:"version"`
	RecordingID    string    `json:"recordingID"`
	KeyID          string    `json:"keyID"`
	Chunks         uint64    `json:"chunks"`
	PlaintextBytes int64     `json:"plaintextBytes"`
	Chain          string    `json:"chain"`
	CreatedAt      time.Time `json:"createdAt"`
	FinalizedAt    time.Time `json:"finalizedAt"`
}

type MetadataStore interface {
	// Reserve atomically claims a new execution and recording identity. Unlike
	// Create, even identical retries conflict, so only one caller may start work.
	Reserve(ctx context.Context, rec ExecutionRecord) error
	// Create inserts a new execution record. It is idempotent on ExecutionID
	// when the content is identical, and returns ErrConflict when it differs.
	Create(ctx context.Context, rec ExecutionRecord) error
	// Transition applies a monotonic state change. A transition to a terminal
	// state is final; later transitions return ErrConflict.
	Transition(ctx context.Context, id string, outcome ExecutionOutcome) error
	// Get returns the record and its last known outcome.
	Get(ctx context.Context, id string) (ExecutionRecord, ExecutionOutcome, error)
	// Audit appends an ordered audit event.
	Audit(ctx context.Context, ev AuditEvent) error
	// List returns records matching the filter, most recent admission first.
	List(ctx context.Context, f Filter) ([]ExecutionRecord, error)
	// Ready probes the backing store. It must fail when the store is unusable.
	Ready(ctx context.Context) error
	Close() error
}

type Operation string

type Options struct {
	Mode              string // "ephemeral" | "external" | "bundled"
	EphemeralDir      string
	EphemeralMaxBytes int64
	DatabaseURL       string
	S3                S3Options
	RecordingKey      []byte
	KeyID             string
}

type Reader interface {
	Manifest() Manifest
	// ReadChunk returns the decrypted plaintext for index after verifying its
	// ciphertext and position.
	ReadChunk(ctx context.Context, index uint64) ([]byte, error)
	// Verify recomputes the hash chain over every chunk and confirms it matches
	// the manifest, detecting tampering and truncation.
	Verify(ctx context.Context) error
	Close() error
}

type Recorder interface {
	// PutChunk encrypts and stores plaintext as index. Indices must start at 0
	// and advance by exactly one; gaps return ErrSeqGap.
	PutChunk(ctx context.Context, index uint64, plaintext []byte) error
	// Finalize writes the manifest binding the chunk count and hash chain.
	Finalize(ctx context.Context, meta FinalizeMeta) error
	// Abort discards partial data for this recording.
	Abort(ctx context.Context) error
}

type RecordingStore interface {
	// Begin opens a new recorder for recordingID.
	Begin(ctx context.Context, recordingID string) (Recorder, error)
	// Open returns a verified reader for a finalized recording.
	Open(ctx context.Context, recordingID string) (Reader, error)
	Ready(ctx context.Context) error
	Close() error
}

type S3Options struct {
	Endpoint       string
	Region         string
	Bucket         string
	CAFile         string
	AccessKey      string
	SecretKey      string
	ForcePathStyle bool
	CreateBucket   bool
}

type State string

type Store interface {
	Metadata() MetadataStore
	Recording() RecordingStore
	Mode() string
	Durability() Durability
	Ready(ctx context.Context) error
	Close() error
}