reporting

Documentation

Overview

Package reporting normalizes structured reports and projection metadata.

Package reporting builds low-noise delta reports from persisted state.

Index

• Constants
• func ProjectionCanonicalHash(projection ReportProjection) (string, error)
• type ClaimSummary
• type Cursor
• type GenerateOptions
• type ItemSummary
• type NegativeQuery
• type Report
• type ReportIdentity
• type ReportProjection
  • func ProjectReport(report Report, capabilities reportschema.ConsumerCapabilities, view string, ...) (ReportProjection, error)
• type ReportProjectionCacheEntry
• type ReportProjectionIdentityInputs
• type ReportProjectionProvenance
• type Snapshot
• type Store
  • func NewStore(configHome string) Store
  • func (s Store) Generate(channel string, now time.Time) (Report, error)
  • func (s Store) GenerateWithOptions(channel string, now time.Time, options GenerateOptions) (Report, error)
  • func (s Store) GetCursor(channel string) (Cursor, error)
  • func (s Store) GetSnapshot(snapshotID string) (Snapshot, error)
  • func (s Store) ProjectReportCached(report Report, capabilities reportschema.ConsumerCapabilities, view string, ...) (ReportProjection, error)

Constants

const (
	SnapshotSchemaVersion = reportschema.ReportingSnapshotSchemaV1
	DefaultFreshnessTTL   = time.Hour
)

Functions

func ProjectionCanonicalHash

func ProjectionCanonicalHash(projection ReportProjection) (string, error)

ProjectionCanonicalHash returns the stable canonical-equivalence hash for a projection.

Types

type ClaimSummary

type ClaimSummary struct {
	ID           string   `json:"id"`
	ItemID       string   `json:"item_id"`
	Kind         string   `json:"kind"`
	Text         string   `json:"text"`
	Confidence   string   `json:"confidence"`
	Evidence     []string `json:"evidence,omitempty"`
	PromotedFrom string   `json:"promoted_from,omitempty"`
	Sensitivity  string   `json:"sensitivity"`
}

type Cursor

type Cursor struct {
	Channel                  string            `json:"channel"`
	LastReportID             string            `json:"last_report_id,omitempty"`
	LastSnapshotID           string            `json:"last_snapshot_id,omitempty"`
	LastReportedAt           time.Time         `json:"last_reported_at,omitempty"`
	LastMeaningfulReportID   string            `json:"last_meaningful_report_id,omitempty"`
	LastMeaningfulSnapshotID string            `json:"last_meaningful_snapshot_id,omitempty"`
	LastMeaningfulItemIDs    []string          `json:"last_meaningful_item_ids,omitempty"`
	LastNegativeEvidenceIDs  []string          `json:"last_negative_evidence_ids,omitempty"`
	FieldHashes              map[string]string `json:"field_hashes,omitempty"`
	ItemHashes               map[string]string `json:"item_hashes,omitempty"`
}

type GenerateOptions

type GenerateOptions struct {
	TriggerID       string
	CheckedSurfaces []string
	CheckedWindow   string
	NegativeQueries []NegativeQuery
	FreshnessTTL    time.Duration
}

type ItemSummary

type ItemSummary struct {
	ID                  string                       `json:"id"`
	Title               string                       `json:"title"`
	DedupeKey           string                       `json:"dedupe_key,omitempty"`
	SameRootCause       []string                     `json:"same_root_cause,omitempty"`
	State               roadmap.State                `json:"state"`
	Priority            roadmap.Priority             `json:"priority"`
	Severity            roadmap.Severity             `json:"severity"`
	Impact              roadmap.ImpactClass          `json:"impact"`
	Readiness           roadmap.HandoffReadiness     `json:"readiness,omitempty"`
	UpdatedAt           time.Time                    `json:"updated_at"`
	ObservedAt          time.Time                    `json:"observed_at"`
	AgeSeconds          int64                        `json:"age_seconds"`
	FreshnessTTLSeconds int64                        `json:"freshness_ttl_seconds"`
	Freshness           string                       `json:"freshness"`
	ObservationSource   string                       `json:"observation_source"`
	Fingerprint         string                       `json:"fingerprint"`
	Sensitivity         string                       `json:"sensitivity"`
	EvidenceRefs        []string                     `json:"evidence_refs,omitempty"`
	Claims              []ClaimSummary               `json:"claims,omitempty"`
	Handoff             *roadmap.HandoffPacket       `json:"handoff,omitempty"`
	Implementation      []roadmap.ImplementationLink `json:"implementation,omitempty"`
}

type NegativeQuery

type NegativeQuery struct {
	ID              string
	Query           string
	CheckedSurfaces []string
	Window          string
}

NegativeQuery describes one absence check that should be attached to a no-change report.

type Report

type Report struct {
	SchemaVersion               string                             `json:"schema_version"`
	SchemaCompatibility         reportschema.CompatibilityGuidance `json:"schema_compatibility"`
	Identity                    ReportIdentity                     `json:"identity"`
	Kind                        string                             `json:"kind"`
	Channel                     string                             `json:"channel"`
	ReportID                    string                             `json:"report_id"`
	TriggerID                   string                             `json:"trigger_id,omitempty"`
	SnapshotID                  string                             `json:"snapshot_id"`
	GeneratedAt                 time.Time                          `json:"generated_at"`
	Outcome                     string                             `json:"outcome"`
	Checked                     bool                               `json:"checked"`
	CheckedSurfaces             []string                           `json:"checked_surfaces,omitempty"`
	NoChange                    bool                               `json:"no_change"`
	MixedFreshness              bool                               `json:"mixed_freshness"`
	FreshnessCounts             map[string]int                     `json:"freshness_counts,omitempty"`
	FieldSensitivity            map[string]string                  `json:"field_sensitivity,omitempty"`
	Claims                      []ClaimSummary                     `json:"claims,omitempty"`
	NegativeEvidence            []reportschema.NegativeEvidence    `json:"negative_evidence,omitempty"`
	InvalidatesNegativeEvidence []string                           `json:"invalidates_negative_evidence,omitempty"`
	FieldDeltas                 []reportschema.FieldDelta          `json:"field_deltas,omitempty"`
	NewItems                    []ItemSummary                      `json:"new_items,omitempty"`
	ChangedItems                []ItemSummary                      `json:"changed_items,omitempty"`
	UnchangedCount              int                                `json:"unchanged_count"`
	TotalCount                  int                                `json:"total_count"`
	Collapsed                   bool                               `json:"collapsed"`
	FullSnapshotStored          bool                               `json:"full_snapshot_stored"`
	PreviousReportID            string                             `json:"previous_report_id,omitempty"`
	LastMeaningfulReportID      string                             `json:"last_meaningful_report_id,omitempty"`
	LastMeaningfulSnapshotID    string                             `json:"last_meaningful_snapshot_id,omitempty"`
	LastMeaningfulItemIDs       []string                           `json:"last_meaningful_item_ids,omitempty"`
}

type ReportIdentity

type ReportIdentity struct {
	ReportID             string `json:"report_id"`
	ContentHash          string `json:"content_hash"`
	CanonicalFingerprint string `json:"canonical_fingerprint"`
}

type ReportProjection

type ReportProjection struct {
	SchemaVersion   string                     `json:"schema_version"`
	ProjectionID    string                     `json:"projection_id"`
	View            string                     `json:"view"`
	Verbosity       string                     `json:"verbosity"`
	Provenance      ReportProjectionProvenance `json:"provenance"`
	Payload         map[string]any             `json:"payload"`
	CanonicalReport Report                     `json:"canonical_report"`
}

func ProjectReport

func ProjectReport(report Report, capabilities reportschema.ConsumerCapabilities, view string, verbosity string) (ReportProjection, error)

type ReportProjectionCacheEntry

type ReportProjectionCacheEntry struct {
	SchemaVersion     string    `json:"schema_version"`
	CacheKey          string    `json:"cache_key"`
	ProjectionID      string    `json:"projection_id"`
	SourceReportID    string    `json:"source_report_id"`
	SourceContentHash string    `json:"source_content_hash"`
	View              string    `json:"view"`
	Verbosity         string    `json:"verbosity"`
	Consumer          string    `json:"consumer"`
	UpdatedAt         time.Time `json:"updated_at"`
}

type ReportProjectionIdentityInputs

type ReportProjectionIdentityInputs struct {
	ProjectionSchemaVersion string                            `json:"projection_schema_version"`
	SourceSchemaVersion     string                            `json:"source_schema_version"`
	SourceContentHash       string                            `json:"source_content_hash"`
	ProjectionPolicyID      string                            `json:"projection_policy_id"`
	Consumer                reportschema.ConsumerCapabilities `json:"consumer"`
	View                    string                            `json:"view"`
	Verbosity               string                            `json:"verbosity"`
}

type ReportProjectionProvenance

type ReportProjectionProvenance struct {
	PolicyID                 string                             `json:"policy_id"`
	CacheKey                 string                             `json:"cache_key,omitempty"`
	IdentityInputs           ReportProjectionIdentityInputs     `json:"identity_inputs"`
	IdentityInputHash        string                             `json:"identity_input_hash"`
	PayloadHash              string                             `json:"payload_hash"`
	CanonicalEquivalenceHash string                             `json:"canonical_equivalence_hash"`
	SourceSchemaVersion      string                             `json:"source_schema_version"`
	SourceReportID           string                             `json:"source_report_id"`
	SourceSnapshotID         string                             `json:"source_snapshot_id"`
	SourceContentHash        string                             `json:"source_content_hash"`
	Consumer                 reportschema.ConsumerCapabilities  `json:"consumer"`
	View                     string                             `json:"view"`
	Verbosity                string                             `json:"verbosity"`
	SourceChanged            bool                               `json:"source_changed"`
	RenderingChanged         bool                               `json:"rendering_changed"`
	DuplicateOfProjectionID  string                             `json:"duplicate_of_projection_id,omitempty"`
	SupersedesProjectionID   string                             `json:"supersedes_projection_id,omitempty"`
	LatestCompatible         bool                               `json:"latest_compatible"`
	StaleCached              bool                               `json:"stale_cached"`
	Downgraded               bool                               `json:"downgraded"`
	OmittedFieldFamilies     []string                           `json:"omitted_field_families,omitempty"`
	Redactions               []reportschema.RedactionProvenance `json:"redactions,omitempty"`
}

type Snapshot

type Snapshot struct {
	SchemaVersion string        `json:"schema_version"`
	SnapshotID    string        `json:"snapshot_id"`
	Channel       string        `json:"channel"`
	GeneratedAt   time.Time     `json:"generated_at"`
	Items         []ItemSummary `json:"items"`
}

type Store

type Store struct {
	Dir     string
	Roadmap roadmap.Store
}

func NewStore

func NewStore(configHome string) Store

func (Store) Generate

func (s Store) Generate(channel string, now time.Time) (Report, error)

func (Store) GenerateWithOptions

func (s Store) GenerateWithOptions(channel string, now time.Time, options GenerateOptions) (Report, error)

func (Store) GetCursor

func (s Store) GetCursor(channel string) (Cursor, error)

func (Store) GetSnapshot

func (s Store) GetSnapshot(snapshotID string) (Snapshot, error)

func (Store) ProjectReportCached

func (s Store) ProjectReportCached(report Report, capabilities reportschema.ConsumerCapabilities, view string, verbosity string) (ReportProjection, error)