audit

type CIContext struct {
	Provider    string `json:"provider"`
	ServerURL   string `json:"server_url,omitempty"`
	Repository  string `json:"repository"`
	EventName   string `json:"event_name"`
	EventRef    string `json:"event_ref"`
	PullRequest string `json:"pull_request,omitempty"`
	BaseRef     string `json:"base_ref,omitempty"`
	HeadRef     string `json:"head_ref,omitempty"`
	HeadSHA     string `json:"head_sha"`
	Workflow    string `json:"workflow,omitempty"`
	Job         string `json:"job,omitempty"`
	Actor       string `json:"actor,omitempty"`
	RunID       string `json:"run_id"`
	RunNumber   string `json:"run_number,omitempty"`
	RunAttempt  string `json:"run_attempt,omitempty"`
}

type Coordinate struct {
	DataSecurity    string `json:"data_security,omitempty"`
	BlastRadius     string `json:"blast_radius,omitempty"`
	NetworkEgress   string `json:"network_egress,omitempty"`
	FilesystemReach string `json:"filesystem_reach,omitempty"`
}

type EgressRow struct {
	Host       string `json:"host"`
	Decision   string `json:"decision"`
	BytesUp    int64  `json:"bytes_up"`
	BytesDown  int64  `json:"bytes_down"`
	DurationMS int64  `json:"duration_ms"`
}

type ProfileDecision struct {
	Allowed    bool       `json:"allowed"`
	Profile    string     `json:"profile,omitempty"`
	Source     string     `json:"source,omitempty"`
	Coordinate Coordinate `json:"coordinate"`
	Reason     string     `json:"reason,omitempty"`
}

type Record struct {
	// ID is a UUID v7 (time-ordered) populated on Append if unset. The
	// stable identifier for an audit row, used to join cross-host records.
	ID        string   `json:"id,omitempty"`
	Timestamp int64    `json:"ts"`
	Version   string   `json:"version,omitempty"`
	Decision  string   `json:"decision"`
	Verb      string   `json:"verb"`
	Argv      []string `json:"argv"`
	ExitCode  int      `json:"exit_code"`
	Error     string   `json:"error,omitempty"`
	// StderrTail is a bounded last-N-bytes capture of the wrapped tool's
	// stderr, populated by pass-through verbs on non-zero exit so the audit
	StderrTail string `json:"stderr_tail,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
	// RepoRoot is git rev-parse --show-toplevel of cwd at invocation time,
	// or empty if cwd was not inside a git repo. Forensic only: tells the
	RepoRoot string `json:"repo_root,omitempty"`
	// CWDSubprocess is os.Getwd() captured by buildBaseRecord at the
	// moment the subprocess saw the world. Differs from CWDAtInvocation
	CWDSubprocess string `json:"cwd_subprocess,omitempty"`
	// CWDAtInvocation is the consumer-resolved operator cwd, populated
	// from verb.Spec.ResolveInvokeCWD when set. Empty when the consumer
	CWDAtInvocation string `json:"cwd_at_invocation,omitempty"`
	// SessionID joins this row to the Claude Code (or other agent harness)
	// session that produced the invocation. Resolution order at write time:
	SessionID string `json:"session_id,omitempty"`
	// AuditOverride is set true when a repo verb ran with
	// --audit-override-dirty: the clean+synced gate refused but the
	AuditOverride bool `json:"audit_override,omitempty"`
	// WorkingTreeStatus is the truncated `git status --porcelain` output
	// captured when a repo verb ran with --audit-override-dirty. Empty for
	WorkingTreeStatus string `json:"working_tree_status,omitempty"`
	// CI carries consumer-validated continuous-integration attribution.
	// The audit package preserves this evidence but does not establish trust.
	CI *CIContext `json:"ci,omitempty"`
	// Egress carries one row per host contacted by the wrapped subprocess
	// when the verb runs through the per-invocation HTTP CONNECT proxy
	Egress []EgressRow `json:"egress,omitempty"`
	// ProfileDecision captures the per-session lockdown-profile evaluation
	// for this verb, when a consumer has wired verb.Spec.OnEvaluate. Absent
	ProfileDecision *ProfileDecision `json:"profile_decision,omitempty"`
	// PolicySkipped is true when the shell-metacharacter validator was
	// bypassed for this invocation. Set by consumers whose verb wiring
	PolicySkipped bool `json:"policy_skipped,omitempty"`
	// Cache is the TTL-cache disposition of a cache-eligible action, e.g. "hit"
	// when a collect served from cache. Empty when no cache was consulted.
	Cache string `json:"cache,omitempty"`
}

type RedactPolicy struct {
	// SecretFlagPatterns is a list of flag-name prefixes (with leading
	// dashes). Matching is "argv token starts with this prefix" so
	SecretFlagPatterns []string

	// IdentifierPatterns is a list of compiled regexes. Any match in
	// Error/StderrTail/Reason fields gets replaced with [REDACTED].
	IdentifierPatterns []*regexp.Regexp
}

type Sink interface {
	Emit(Span)
}

type SinkFunc func(Span)

type Span struct {
	Name       string
	StartUnix  int64
	DurationMS int64
	Error      bool
	Attributes map[string]any
}

type Writer struct {
	// Path is the JSONL file. Must be set.
	Path string
	// Now is used for timestamps. Tests override. Defaults to time.Now.
	Now func() time.Time
	// MaxSizeMB is the rotation trigger. Zero uses lumberjack's default (100).
	MaxSizeMB int
	// MaxBackups caps the number of rotated files retained. Zero keeps all.
	MaxBackups int
	// MaxAgeDays prunes rotated files older than this. Zero disables.
	MaxAgeDays int
	// Compress gzips rotated files.
	Compress bool

	// Version stamps rows whose Record.Version is unset, else BuildVersion.
	// Generated binaries set it to their -ldflags version.
	Version string

	// Sinks receive each appended record as a Span, after the JSONL write.
	// A panicking or slow sink is the consumer's problem, never the log's.
	Sinks []Sink
	// contains filtered or unexported fields
}