ledger

type AuditFilters struct {
	// EventType filters by exact event type label. Empty means no filter.
	EventType string

	// ActorID filters by exact actor identifier. Empty means no filter.
	ActorID string

	// SubjectID filters by exact subject identifier — the principal the audited
	// action targeted. Empty means no filter. Unlike ActorID (who performed the
	// action), SubjectID lets an admin investigate impersonation where actor !=
	// subject (#1290). For non-admin callers it composes with the actor-self
	// scoping the auditquery policy enforces, so it only ever narrows within the
	// caller's own actions.
	SubjectID string

	// TenantID scopes the query to a tenant boundary. A non-empty value matches
	// that tenant's rows PLUS tenant-less system/framework rows (tenant_id == "" —
	// e.g. bootstrap.auth.fail and other pre-auth events that have no principal
	// tenant), and NEVER another tenant's rows. Empty means no filter (generic
	// store consumers). The auditquery handler always sets this from
	// principal.TenantID (epic #1337 PR-2a) — that handler is the isolation
	// boundary. Standard multi-tenant audit semantics: a tenant admin sees its own
	// tenant + global/system events. DB-layer RLS (PR-3) is the backstop.
	TenantID string

	// TraceID filters by exact trace_id. Empty means no filter. This field
	// allows correlating audit entries with distributed traces for operational
	// investigation. trace_id is an observability field and is NOT part of the
	// HMAC hash chain.
	TraceID string

	// From filters entries with Timestamp >= From. Zero means no lower bound.
	From time.Time

	// To filters entries with Timestamp <= To. Zero means no upper bound.
	To time.Time
}

type Entry struct {
	// SeqNo is the monotonically increasing sequence number assigned by the
	// store on Append. Starts at 1. Zero value indicates the entry has not
	// yet been persisted.
	SeqNo int64

	// ID is an optional opaque store-assigned identifier (UUID/ULID). The
	// store may populate this on Append; callers must not rely on it for
	// chain ordering — SeqNo is authoritative.
	ID string

	// EventID is the business-layer event identifier (UUID). Used as part of
	// the HMAC input and as the idempotency fingerprint key.
	EventID string

	// EventType is the event type label (e.g. "user.login", "config.updated").
	EventType string

	// ActorID identifies the principal that triggered the event (the
	// impersonator in OAuth `act.sub` semantics; equals SubjectID for normal
	// non-impersonated flows).
	ActorID string

	// SubjectID is the OAuth subject-of-record (the end-user's stable
	// identity, OAuth `sub`). Empty string when not available — the column is
	// NOT NULL with no DEFAULT in the DB schema (043_audit_entries_v2.sql);
	// callers (PG Store INSERT) supply the zero value explicitly so the chain
	// reflects the producer's lack of injection rather than a sentinel DEFAULT.
	//
	// Output policy at the auditquery API boundary (DTO exposure / redaction /
	// admin-gated filtering) is decided by issue #1229 §4 (PR-A2 sealed
	// construction); issue #1219 tracks the contract.yaml DTO extension.
	SubjectID string

	// TenantID is the tenant boundary identifier for multi-tenant deployments.
	// Empty string when not available. NOT NULL no-DEFAULT in DB. See SubjectID
	// for the auditquery output policy reference.
	TenantID string

	// SessionID is the session identifier of the triggering request (server-
	// side session binding). Empty string when not available. NOT NULL
	// no-DEFAULT in DB. SessionID matches `pkg/redaction` sensitive-key set;
	// issue #1229 §4 may strip it from the auditquery DTO entirely.
	SessionID string

	// CorrelationID carries the cross-cell correlation identifier from the
	// outbox observability envelope. Empty string when not available. NOT NULL
	// no-DEFAULT in DB.
	CorrelationID string

	// TraceID carries the OpenTelemetry trace id from the outbox observability
	// envelope. Observability metadata, NOT an audited fact — it is deliberately
	// EXCLUDED from the HMAC hash chain (Protocol.ComputeHash) so audit
	// tamper-evidence is unchanged. Empty string when absent. NOT NULL no-DEFAULT
	// in DB (app supplies explicit value).
	// Writes are restricted to the audit appender by AUDIT-TRACE-ID-WRITE-CALLER-01 (tools/archtest).
	TraceID string

	// OccurredAt is the producer-clock event time (distinct from Timestamp
	// which is the ledger persistence / HMAC time). The audit chain pins both
	// times so consumers can distinguish "when the business event happened"
	// from "when the audit row was sealed". NOT NULL no-DEFAULT in DB; the
	// Go zero (`time.Time{}`) marshals as epoch when no value is supplied.
	OccurredAt time.Time

	// Timestamp is the event wall-clock time in UTC. Used in the HMAC input
	// as UnixNano so the hash is timestamp-sensitive.
	Timestamp time.Time

	// Payload is the arbitrary JSON payload associated with the event. Strict
	// validation (valid JSON) is enforced by the store on Append.
	Payload []byte

	// PrevHash is the Hash of the immediately preceding entry in the chain.
	// Empty for the first entry (SeqNo == 1). Computed by the store.
	PrevHash string

	// Hash is the HMAC-SHA256 hex digest of this entry computed by
	// Protocol.ComputeHash. Computed by the store on Append.
	Hash string
}

type IdempotencyContentFingerprint struct{}

type IdempotencyMode interface {
	// contains filtered or unexported methods
}

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

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

type NamespaceID string

type Option func(*Protocol) error

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

type QueryStore interface {
	// Query has identical semantics to Store.Query — see that method's godoc for
	// the full contract (keyset pagination + params.Sort requirement, the vis
	// row-visibility obligation enforced on the actor_id owner column, and the
	// RowScopeAll fail-closed rule). This narrow read-only subset exists so
	// read-side aggregators (MultiStore) implement only Query, not the write path.
	Query(ctx context.Context, vis tenant.RowVisibility, filters AuditFilters, params query.ListParams) ([]*Entry, error)
}

type RestartRecoveryMode interface {
	// contains filtered or unexported methods
}

type RestartRecoveryStrictTailVerify struct{}

type Store interface {
	// Protocol returns the immutable protocol decisions backing this store.
	// Callers use it for composition-time invariant checks such as namespace
	// disjointness; implementations must not return nil.
	Protocol() *Protocol

	// Append persists a new entry into the namespace's hash chain. Computes
	// PrevHash from Tail, assigns SeqNo, and computes Hash via Protocol.ComputeHash.
	// Rejects invalid JSON payload (ErrValidationFailed) and duplicate content
	// fingerprints (ErrAuditLedgerAlreadyExists). Thread-safe.
	Append(ctx context.Context, e *Entry) error

	// Tail returns the current chain tail snapshot (SeqNo, PrevHash, EntryCount).
	// Returns zero TailSnapshot when the store is empty (not an error).
	Tail(ctx context.Context) (TailSnapshot, error)

	// GetBySeq fetches a single entry by sequence number. The vis obligation
	// is enforced on the actor_id OWNER column: if the entry exists but
	// vis.Allows(entry.ActorID) is false, the implementation returns
	// ErrAuditLedgerNotFound (IDOR-safe collapse — existence is not leaked).
	// vis must be valid (NewRowVisibility must succeed). A vis carrying
	// RowScopeAll is fail-closed on every backend (RowScopeAllUnsupportedError)
	// until the audited super-admin path lands (epic #1337 PR-5).
	//
	// Tenant axis NOT enforced here (deliberate, tracked #1342 / #1618): GetBySeq
	// enforces ONLY the owner dimension (vis on actor_id). Unlike Query it takes no
	// AuditFilters, so it carries no tenant predicate — by seq_no it reads the
	// namespace-global hash chain (the same chain-primitive surface as Tail/Verify),
	// where seq_no is unique per namespace, not per (namespace, tenant). It has NO
	// production caller today (chain replay / conformance only). A future
	// tenant-FACING by-seq read endpoint MUST add a tenant filter (an AuditFilters /
	// tenant.TenantID parameter that returns ErrAuditLedgerNotFound on tenant
	// mismatch) rather than rely on this owner-only check; that is deferred until
	// such a consumer exists (adding it now would be dead plumbing). The deeper fix
	// — a per-(namespace, tenant) chain with RLS so seq reads are tenant-scoped at
	// the DB — is #1618.
	GetBySeq(ctx context.Context, vis tenant.RowVisibility, seq int64) (*Entry, error)

	// Query lists entries matching AuditFilters using keyset cursor pagination
	// defined by params (Limit + decoded CursorValues + Sort). It returns up to
	// params.FetchLimit() (Limit+1) rows for N+1 hasMore detection, ordered by
	// params.Sort. params.Sort must be non-empty (callers pass QuerySort);
	// an empty Sort is a programmer error and yields ErrValidationFailed.
	// Returns an empty (non-nil) slice when no entries match.
	//
	// vis is the row-visibility obligation enforced on the actor_id owner column.
	// Self/device scopes restrict results to entries whose actor_id matches the
	// obligation subject. Tenant scope returns all matching rows in the tenant.
	// vis must be valid (NewRowVisibility must succeed). A vis carrying
	// RowScopeAll is fail-closed on every backend (RowScopeAllUnsupportedError)
	// until the audited super-admin path lands (epic #1337 PR-5).
	Query(ctx context.Context, vis tenant.RowVisibility, filters AuditFilters, params query.ListParams) ([]*Entry, error)

	// Verify re-computes the HMAC for each entry in [fromSeq, toSeq] and checks
	// chain linkage (PrevHash). Returns valid=true and firstInvalidSeq=-1 when
	// all entries are intact. Returns valid=false and the first invalid seq_no
	// when tampering is detected.
	Verify(ctx context.Context, fromSeq, toSeq int64) (valid bool, firstInvalidSeq int64, err error)

	// RepoReady is a differentiated readiness check that exercises the
	// audit_entries relation directly. SQL-backed implementations issue a
	// representative query (e.g. Tail) so that schema/migration drift or
	// table-level permission loss surfaces independently from the pool-level
	// postgres_ready ping. In-memory implementations return nil (always ready).
	RepoReady(ctx context.Context) error
}

type TailSnapshot struct {
	// SeqNo is the sequence number of the last committed entry.
	// Zero if the store is empty.
	SeqNo int64

	// PrevHash is the Hash of the last committed entry.
	// Empty if the store is empty.
	PrevHash string

	// EntryCount is the total number of entries in the store.
	EntryCount int64
}