audit

type ArchiveMode string

type ArchiveRecord struct {
	ID         string    `json:"id"`
	Month      string    `json:"month"` // 2026-06
	AdapterRef string    `json:"adapter_ref,omitempty"`
	ObjectName string    `json:"object_name"`
	RowCount   int64     `json:"row_count"`
	FirstID    int64     `json:"first_id"`
	LastID     int64     `json:"last_id"`
	FirstAt    time.Time `json:"first_at"`
	LastAt     time.Time `json:"last_at"`
	SizeBytes  int64     `json:"size_bytes"`
	SHA256     string    `json:"sha256"`
	CreatedAt  time.Time `json:"created_at"`
}

type Archiver struct {
	Pool      *pgxpool.Pool
	Stores    Stores
	Retention func(ctx context.Context) (Retention, error)
	Clock     clock.Clock
	Logger    *zap.Logger
	Interval  time.Duration

	// Holds names the enabled audit sinks that have not been sent every event
	// in [lo, hi) (R-386). A month any of them holds is neither archived nor
	// removed this pass: archiving it now would record an archive for rows
	// still in the live log. Nil holds nothing.
	Holds func(ctx context.Context, lo, hi time.Time) ([]string, error)

	// Audit records that a month was held, once per month per process. The
	// archiver's own role cannot write the log, so this is the application's
	// writer. Nil records nothing.
	Audit func(ctx context.Context, e Event)
	// contains filtered or unexported fields
}

type Archives struct {
	Pool   *pgxpool.Pool
	Stores Stores
}

type Cursor struct {
	TxID uint64
	ID   int64
}

type Encoder func(line json.RawMessage) (json.RawMessage, error)

type Event struct {
	PrincipalKind PrincipalKind
	PrincipalID   string

	// OnBehalfOf is the owning user when a delegated token acted (R-229).
	// Authorization already resolved through the owner; the audit log records
	// both so "what did this person do" stays answerable.
	OnBehalfOf string

	Action     string
	AppID      string
	TargetKind string
	TargetID   string
	RequestID  string
	Detail     map[string]any

	// Outcome is success, denied or failed (R-379). Empty derives it from
	// the action (OutcomeOf), which is right for every event whose action
	// name already says how it ended. A finished deploy, whose one action
	// covers both, sets it.
	Outcome Outcome
}

type Line struct {
	ID            int64          `json:"id"`
	OccurredAt    time.Time      `json:"occurred_at"`
	PrincipalKind string         `json:"principal_kind"`
	PrincipalID   *string        `json:"principal_id"`
	OnBehalfOf    *string        `json:"on_behalf_of"`
	Action        string         `json:"action"`
	AppID         *string        `json:"app_id"`
	TargetKind    *string        `json:"target_kind"`
	TargetID      *string        `json:"target_id"`
	RequestID     *string        `json:"request_id"`
	Detail        map[string]any `json:"detail"`
	SchemaVersion *int           `json:"schema_version"`
	Outcome       *string        `json:"outcome"`
	SourceIP      *string        `json:"source_ip"`
	PeerIP        *string        `json:"peer_ip"`
	UserAgent     *string        `json:"user_agent"`
	ActorName     *string        `json:"actor_name"`
	ActorEmail    *string        `json:"actor_email"`
}

type Outcome string

type PrincipalKind string

type Query struct {
	// Action matches a prefix, so "app." finds every app event and
	// "session.denied" finds exactly one kind. A prefix rather than a substring
	// because actions are dotted namespaces — a substring match would make
	// "grant.delete" a result for a search for "delete".
	Action string

	// Actions are more prefixes, any of which matches, alongside Action:
	// "apps someone added or deleted" is app.create or app.delete, and filters
	// otherwise combine with AND.
	Actions []string

	AppID       string
	PrincipalID string

	// PrincipalKind narrows to one kind of actor: user, token, system or
	// anonymous. The only way to find anonymous events, which have no ID, and
	// every system process at once rather than one at a time.
	PrincipalKind string

	// TargetKind and TargetID narrow to what the action was done to — "every
	// change to this user", "everything done to any role". Exact matches.
	TargetKind string
	TargetID   string

	// Involving narrows to events where one ID is on either side: the actor
	// (or the person a token acted for) or the target. "Everything to do with
	// this account" — what it did and what was done to it — which the actor and
	// target filters cannot say, because filters combine with AND.
	Involving string

	// Since and Until bound when it happened: Since inclusive, Until
	// exclusive, so consecutive ranges neither overlap nor leave a gap. Zero
	// means unbounded.
	Since time.Time
	Until time.Time

	// Limit defaults to 100, capped at 500. PageSize is the clamp.
	Limit int

	// Cursor is the ID of the last record on the previous page. The log is
	// append-only with monotonic IDs, so "before this ID" is a stable page
	// boundary in a way an offset is not — with an offset, events arriving
	// between requests shift every later page.
	Cursor int64
}

type ReadThrottle struct {
	Every time.Duration
	// contains filtered or unexported fields
}

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

type Record struct {
	ID            int64          `json:"id"`
	OccurredAt    time.Time      `json:"occurred_at"`
	PrincipalKind string         `json:"principal_kind"`
	PrincipalID   string         `json:"principal_id,omitempty"`
	OnBehalfOf    string         `json:"on_behalf_of,omitempty"`
	Action        string         `json:"action"`
	AppID         string         `json:"app_id,omitempty"`
	TargetKind    string         `json:"target_kind,omitempty"`
	TargetID      string         `json:"target_id,omitempty"`
	RequestID     string         `json:"request_id,omitempty"`
	Detail        map[string]any `json:"detail,omitempty"`

	// What R-379 adds. Empty on events written before it.
	Outcome       string `json:"outcome,omitempty"`
	SourceIP      string `json:"source_ip,omitempty"`
	PeerIP        string `json:"peer_ip,omitempty"`
	UserAgent     string `json:"user_agent,omitempty"`
	ActorName     string `json:"actor_name,omitempty"`
	ActorEmail    string `json:"actor_email,omitempty"`
	SchemaVersion int    `json:"schema_version"`
}

type Retention struct {
	// Months the live log keeps. Zero is DefaultRetentionMonths.
	Months int
	// Archive is the mode. Empty is ArchiveKeep.
	Archive ArchiveMode
	// Destination is the backup adapter an export goes to. Empty is the
	// default backup destination.
	Destination string
}

type Store interface {
	Writer(ctx context.Context, name string) (io.WriteCloser, error)
	Reader(ctx context.Context, name string) (io.ReadCloser, error)
}

type Stores struct {
	// Kept is Pando's own directory, for ArchiveKeep.
	Kept Store

	// Export resolves a backup adapter by reference, empty meaning the
	// default, and returns the reference it resolved to.
	Export func(ref string) (Store, string, error)
}

type StreamPage struct {
	// Events are native lines (design 12 §6.1): each row as the archiver
	// writes it, oldest first.
	Events []json.RawMessage

	// IDs are the events' ids, in the same order.
	IDs []int64

	// Cursor is where the next read starts. It has moved past every event
	// scanned, including those a filter dropped.
	Cursor Cursor

	// CaughtUp says the read reached the horizon: nothing settled lies past
	// Cursor right now.
	CaughtUp bool
}

type StreamQuery struct {
	After Cursor

	// Limit defaults to 500, capped at 1000 (StreamPageSize).
	Limit int

	// Actions and Exclude are prefixes. An event is read when it matches one
	// of Actions (or Actions is empty) and none of Exclude. The cursor moves
	// past the events a filter drops, so a filtered reader never reads them
	// again.
	Actions []string
	Exclude []string

	// Since and Until bound occurred_at, Since inclusive and Until exclusive,
	// for an export of a range. Zero is unbounded.
	Since time.Time
	Until time.Time
}

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