controlaudit

type Action string

type ControlAuditRecord struct {
	ID              string    `json:"id"`
	OccurredAt      time.Time `json:"occurred_at"`
	Actor           string    `json:"actor"`
	Action          Action    `json:"action"`
	ResourceKind    string    `json:"resource_kind"`
	ResourceID      string    `json:"resource_id"`
	ResourceVersion *int      `json:"resource_version,omitempty"`
	Summary         string    `json:"summary"`
	Metadata        *Metadata `json:"metadata,omitempty"`
}

type ListFilter struct {
	// ResourceKind constrains results to a specific resource kind
	// (e.g. "surface", "profile").
	ResourceKind string

	// ResourceID constrains results to a specific resource logical ID.
	ResourceID string

	// Actor constrains results to records emitted by a specific actor.
	Actor string

	// Action constrains results to a specific action constant.
	Action Action

	// Limit caps the number of records returned. Zero means "use default".
	// Values above MaxListLimit are clamped to MaxListLimit by the repository.
	Limit int
}

type Metadata struct {
	// SurfaceID is the logical surface ID referenced by the mutated resource,
	// populated for profile records to capture the owning surface.
	SurfaceID string `json:"surface_id,omitempty"`

	// DeprecationReason is the operator-supplied reason for deprecation.
	DeprecationReason string `json:"deprecation_reason,omitempty"`

	// SuccessorSurfaceID is the successor surface ID recorded on deprecation.
	SuccessorSurfaceID string `json:"successor_surface_id,omitempty"`

	// Reason is a generic operator-supplied reason, used for grant lifecycle actions.
	Reason string `json:"reason,omitempty"`
}

type Repository interface {
	// Append persists a single audit record. The record is immutable after append.
	Append(ctx context.Context, rec *ControlAuditRecord) error

	// List returns audit records in descending occurred_at order (newest first).
	// The filter may constrain results; a zero-value filter returns all records
	// up to the effective limit.
	List(ctx context.Context, f ListFilter) ([]*ControlAuditRecord, error)
}