models

type APIKey struct {
	ID        uuid.UUID  `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	TenantID  uuid.UUID  `gorm:"type:uuid;not null;index" json:"tenant_id"`
	KeyHash   string     `gorm:"size:64;not null;uniqueIndex" json:"-"`
	Label     string     `gorm:"size:200;not null" json:"label"`
	Prefix    string     `gorm:"size:8;not null" json:"prefix"`
	CreatedAt time.Time  `json:"created_at"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`

	// ExpiresAt: instant after which the key stops authenticating (auth.ValidateKey).
	// NULL = never expires. Set at issue (--ttl) or by rotation's grace window.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// LastUsedAt: best-effort last successful validation (errors ignored). NULL =
	// never used. Admin listing uses it to spot stale keys.
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`

	// SubjectID pins the key to a unified authz subject. NULL = tenant service
	// principal ("svc:<tenant_id>"); set = resolved subject id per request.
	SubjectID *string `gorm:"size:255;index" json:"subject_id,omitempty"`

	Tenant *Tenant `gorm:"foreignKey:TenantID" json:"tenant,omitempty"`
}

type ChainPrevious struct {
	Scope    string `json:"scope"`
	EdgeType string `json:"edge_type"`
}

type CleanupQueue struct {
	ID             uuid.UUID  `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	TenantID       uuid.UUID  `gorm:"type:uuid;not null;index:idx_cleanup_pending,priority:1" json:"tenant_id"`
	DocAID         uuid.UUID  `gorm:"type:uuid;not null" json:"doc_a_id"`
	DocBID         uuid.UUID  `gorm:"type:uuid;not null" json:"doc_b_id"`
	Similarity     float64    `gorm:"not null" json:"similarity"`
	DetectedAt     time.Time  `gorm:"not null;default:NOW()" json:"detected_at"`
	ResolvedAt     *time.Time `gorm:"index:idx_cleanup_pending,priority:2" json:"resolved_at,omitempty"`
	Resolution     *string    `gorm:"size:32" json:"resolution,omitempty"`
	ResolutionNote *string    `gorm:"type:text" json:"resolution_note,omitempty"`
	MergedInto     *uuid.UUID `gorm:"type:uuid" json:"merged_into,omitempty"`
}

type DeletionEvent struct {
	ID           uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
	TenantID     uuid.UUID  `gorm:"type:uuid;not null;index" json:"tenant_id"`
	DocumentPath string     `gorm:"type:text;not null" json:"document_path"`
	DocType      string     `gorm:"size:32" json:"doc_type,omitempty"`
	Reason       string     `gorm:"size:32;not null" json:"reason"`
	ArchivedAt   *time.Time `json:"archived_at,omitempty"`
	DeletedAt    time.Time  `gorm:"not null;default:now()" json:"deleted_at"`
}

type DocTypePolicy struct {
	DocType           string           `gorm:"size:32;primaryKey" json:"doc_type"`
	ExpirationAgeDays *int             `json:"expiration_age_days"`
	DuplicateGuard    *bool            `json:"duplicate_guard"`
	CleanupScan       *bool            `json:"cleanup_scan"`
	LintStaleCheck    *bool            `json:"lint_stale_check"`
	Embed             *bool            `json:"embed"`
	DefaultSearch     *bool            `json:"default_search"`
	Prunable          *bool            `json:"prunable"`
	WriteMode         *WriteMode       `gorm:"size:16" json:"write_mode"`
	SlugFormat        *SlugFormat      `gorm:"size:16" json:"slug_format"`
	Subcategory       *SubcategoryRule `gorm:"size:16" json:"subcategory"`
	Rules             datatypes.JSON   `gorm:"type:jsonb;not null;default:'{}'" json:"rules"`
}

type Document struct {
	ID          uuid.UUID `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	TenantID    uuid.UUID `gorm:"type:uuid;not null;default:'00000000-0000-0000-0000-000000000001';index" json:"tenant_id"`
	Category    string    `gorm:"size:50;not null" json:"category"`
	Subcategory *string   `gorm:"size:100" json:"subcategory,omitempty"`
	Slug        string    `gorm:"size:100;not null" json:"slug"`
	Title       string    `gorm:"size:500;not null" json:"title"`
	DocType     string    `gorm:"size:32;not null;default:'reference';index" json:"doc_type"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
	// ArchivedAt marks a document retired by the retention sweep. Non-NULL =
	// excluded from all reads; hard-deleted after the delete grace period.
	ArchivedAt *time.Time `gorm:"index:idx_documents_archived_at" json:"archived_at,omitempty"`
	// ArchiveReason names the lifecycle rule that archived the doc (empty until
	// archived); carried into the deletion audit at hard-delete.
	ArchiveReason string `gorm:"size:32" json:"archive_reason,omitempty"`
	// LastAccessedAt is bumped when a search serves the doc's sections;
	// COALESCE(last_accessed_at, created_at) drives access-recency eviction (D1).
	LastAccessedAt *time.Time `json:"last_accessed_at,omitempty"`
	// Pinned exempts the doc from access-based eviction regardless of age (D4).
	Pinned bool `gorm:"not null;default:false" json:"pinned"`
	// ContentHash is hex(sha256(raw markdown)); powers the write-guard exact-dup
	// short-circuit. Nullable/unbackfilled — pre-migration docs fall to the centroid.
	ContentHash string `gorm:"size:64;index" json:"-"`

	// Scope gates a document's applicability: empty = always applies, non-empty = a
	// space-separated pattern list matched against a read-time scope (drives
	// conditional includes). Allowed on any doc_type.
	Scope *string `gorm:"column:scope;size:500" json:"scope,omitempty"`

	// Display-only owning-tenant labels (not columns) — populated by the service
	// for list responses so browse shows the tenant name/type, like search does.
	TenantName string `gorm:"-" json:"tenant_name,omitempty"`
	TenantType string `gorm:"-" json:"tenant_type,omitempty"`

	Tenant   *Tenant   `gorm:"foreignKey:TenantID" json:"-"`
	Sections []Section `gorm:"foreignKey:DocumentID;constraint:OnDelete:CASCADE" json:"sections,omitempty"`
}

type Edge struct {
	ID               uuid.UUID `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	TenantID         uuid.UUID `gorm:"type:uuid;not null;index" json:"tenant_id"`
	SourceDocumentID uuid.UUID `gorm:"type:uuid;not null;index" json:"source_document_id"`
	TargetDocumentID uuid.UUID `gorm:"type:uuid;not null;index" json:"target_document_id"`
	EdgeType         string    `gorm:"size:32;not null" json:"edge_type"`
	ActorSubject     string    `gorm:"size:255" json:"actor_subject"`
	CreatedAt        time.Time `json:"created_at"`

	// Association fields exist only so AutoMigrate emits the OnDelete:CASCADE FKs.
	Source *Document `gorm:"foreignKey:SourceDocumentID;constraint:OnDelete:CASCADE" json:"-"`
	Target *Document `gorm:"foreignKey:TargetDocumentID;constraint:OnDelete:CASCADE" json:"-"`
}

type EffectivePolicy struct {
	ExpirationAgeDays int
	DuplicateGuard    bool
	CleanupScan       bool
	LintStaleCheck    bool
	Embed             bool
	DefaultSearch     bool
	Prunable          bool
	WriteMode         WriteMode
	SlugFormat        SlugFormat
	Subcategory       SubcategoryRule
	ChainPrevious     *ChainPrevious
	RawRules          map[string]json.RawMessage
}

type EmbeddingMetadata struct {
	ID         uint      `gorm:"primaryKey" json:"id"`
	Provider   string    `gorm:"not null" json:"provider"`
	Model      string    `gorm:"not null" json:"model"`
	Dimensions int       `gorm:"not null" json:"dimensions"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type ImportJob struct {
	ID       uuid.UUID `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	TenantID uuid.UUID `gorm:"type:uuid;not null;index" json:"tenant_id"`

	// Status is one of the ImportJobStatus* constants.
	Status  string `gorm:"size:20;not null;default:'queued'" json:"status"`
	Archive []byte `gorm:"type:bytea" json:"-"`

	// Progress counters, updated by the worker as it processes the archive.
	Total    int `gorm:"not null;default:0" json:"total"`
	Imported int `gorm:"not null;default:0" json:"imported"`
	Skipped  int `gorm:"not null;default:0" json:"skipped"`
	Failed   int `gorm:"not null;default:0" json:"failed"`

	// Error carries the terminal failure reason when Status == failed.
	Error string `json:"error,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type InstanceConfig struct {
	ID uint `gorm:"primaryKey" json:"id"`

	// GlobalsSeeded guards the one-time env→DB seed of the runtime globals on an
	// existing singleton row; fresh rows are inserted already-seeded.
	GlobalsSeeded bool `gorm:"not null;default:false" json:"-"`

	// Instance toggles.
	HistoryEnabled bool `gorm:"not null;default:false" json:"history_enabled"`

	// Retrieval tuning.
	MMRLambda            float64 `gorm:"not null;default:0.5" json:"mmr_lambda"`
	CandidatePool        int     `gorm:"not null;default:20" json:"candidate_pool"`
	SnippetChars         int     `gorm:"not null;default:400" json:"snippet_chars"`
	HistoryRetentionDays int     `gorm:"not null;default:90" json:"history_retention_days"`

	// New-tenant toggle defaults + the global near-duplicate cutoff.
	DuplicateGuardDefault bool    `gorm:"not null;default:true" json:"duplicate_guard_default"`
	CleanupScanDefault    bool    `gorm:"not null;default:true" json:"cleanup_scan_default"`
	DuplicateThreshold    float64 `gorm:"not null;default:0.85" json:"duplicate_threshold"`

	// Access / self-service (signup_domains + admin_emails are CSV). admin_emails
	// seeds bootstrap admins at startup; live grant/revoke is via the admin UI.
	SelfServicePolicy string `gorm:"size:16;not null;default:'open'" json:"self_service_policy"`
	SignupDomains     string `gorm:"type:text;not null;default:''" json:"signup_domains"`
	AdminEmails       string `gorm:"type:text;not null;default:''" json:"admin_emails"`

	// Maintenance.
	CleanupEnabled       bool `gorm:"not null;default:true" json:"cleanup_enabled"`
	CleanupIntervalHours int  `gorm:"not null;default:24" json:"cleanup_interval_hours"`

	// Retention sweep + metrics retention (sweep on by default; metrics 90d).
	RetentionSweepEnabled bool `gorm:"not null;default:true" json:"retention_sweep_enabled"`
	MetricsRetentionDays  int  `gorm:"not null;default:90" json:"metrics_retention_days"`

	// HTTP hardening.
	RateLimitRPS      float64 `gorm:"not null;default:20" json:"rate_limit_rps"`
	RateLimitBurst    int     `gorm:"not null;default:40" json:"rate_limit_burst"`
	TrustedProxyDepth int     `gorm:"not null;default:0" json:"trusted_proxy_depth"`
	MaxRequestBytes   int64   `gorm:"not null;default:1048576" json:"max_request_bytes"`

	// Logging + outbound webhook (empty disables).
	LogLevel   string `gorm:"size:16;not null;default:'info'" json:"log_level"`
	WebhookURL string `gorm:"type:text;not null;default:''" json:"webhook_url"`

	// RequireConfigListener fails /~/ready when the config-invalidation listener is
	// dead. Off by default: a single replica has no peers to fall behind, so a dead
	// listener is harmless there; multi-replica turns it on.
	RequireConfigListener bool `gorm:"not null;default:false" json:"require_config_listener"`

	UpdatedAt time.Time `json:"updated_at"`
}

type InstanceConfigPatch struct {
	MMRLambda             *float64 `json:"mmr_lambda"`
	CandidatePool         *int     `json:"candidate_pool"`
	SnippetChars          *int     `json:"snippet_chars"`
	HistoryEnabled        *bool    `json:"history_enabled"`
	HistoryRetentionDays  *int     `json:"history_retention_days"`
	DuplicateGuardDefault *bool    `json:"duplicate_guard_default"`
	CleanupScanDefault    *bool    `json:"cleanup_scan_default"`
	DuplicateThreshold    *float64 `json:"duplicate_threshold"`
	SelfServicePolicy     *string  `json:"self_service_policy"`
	SignupDomains         *string  `json:"signup_domains"`
	AdminEmails           *string  `json:"admin_emails"`
	CleanupEnabled        *bool    `json:"cleanup_enabled"`
	CleanupIntervalHours  *int     `json:"cleanup_interval_hours"`
	RetentionSweepEnabled *bool    `json:"retention_sweep_enabled"`
	MetricsRetentionDays  *int     `json:"metrics_retention_days"`
	RateLimitRPS          *float64 `json:"rate_limit_rps"`
	RateLimitBurst        *int     `json:"rate_limit_burst"`
	TrustedProxyDepth     *int     `json:"trusted_proxy_depth"`
	MaxRequestBytes       *int64   `json:"max_request_bytes"`
	LogLevel              *string  `json:"log_level"`
	WebhookURL            *string  `json:"webhook_url"`
	RequireConfigListener *bool    `json:"require_config_listener"`
}

type MetricEvent struct {
	ID        uuid.UUID  `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	TenantID  uuid.UUID  `gorm:"type:uuid;not null" json:"tenant_id"`
	EventType string     `gorm:"size:16;not null" json:"event_type"`
	DocID     *uuid.UUID `gorm:"type:uuid" json:"doc_id,omitempty"`
	DocType   string     `gorm:"size:32" json:"doc_type,omitempty"`
	CreatedAt time.Time  `gorm:"not null;default:now()" json:"created_at"`
}

type MutationHistory struct {
	ID           uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
	TenantID     uuid.UUID  `gorm:"type:uuid;not null;index" json:"tenant_id"`
	DocumentID   uuid.UUID  `gorm:"type:uuid;not null;index:idx_mutation_history_doc_time,priority:1" json:"document_id"`
	SectionID    *uuid.UUID `gorm:"type:uuid" json:"section_id,omitempty"`
	DocumentPath string     `gorm:"type:text" json:"document_path"`
	OpType       string     `gorm:"size:32;not null" json:"op_type"`
	ActorSubject string     `gorm:"size:255" json:"actor_subject"`
	ActorEmail   *string    `gorm:"type:text" json:"actor_email,omitempty"`
	APIKeyID     *uuid.UUID `gorm:"type:uuid" json:"api_key_id,omitempty"`
	Before       *string    `gorm:"type:text" json:"before,omitempty"`
	CreatedAt    time.Time  `gorm:"index:idx_mutation_history_doc_time,priority:2,sort:desc" json:"created_at"`
}

type OverrideLog struct {
	ID           uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
	TenantID     uuid.UUID  `gorm:"type:uuid;not null;index:idx_override_tenant_time,priority:1" json:"tenant_id"`
	Tool         string     `gorm:"size:32;not null" json:"tool"`
	TargetID     *uuid.UUID `gorm:"type:uuid" json:"target_id,omitempty"`
	OverrideType string     `gorm:"size:32;not null" json:"override_type"`
	Reason       string     `gorm:"type:text;not null" json:"reason"`
	APIKeyID     *uuid.UUID `gorm:"type:uuid" json:"api_key_id,omitempty"`
	CreatedAt    time.Time  `gorm:"index:idx_override_tenant_time,priority:2,sort:desc" json:"created_at"`
}

type Section struct {
	ID         uuid.UUID       `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	DocumentID uuid.UUID       `gorm:"type:uuid;not null;index:idx_section_doc_ord" json:"document_id"`
	Ordinal    int             `gorm:"not null;index:idx_section_doc_ord" json:"ordinal"`
	Heading    *string         `gorm:"size:500" json:"heading,omitempty"`
	Content    string          `gorm:"type:text;not null" json:"content"`
	Embedding  pgvector.Vector `gorm:"type:vector" json:"-"`
	VerifiedAt *time.Time      `gorm:"index:idx_sections_verified_at" json:"verified_at,omitempty"`
	// VerifyHints are file/symbol/line references (file:symbol, file:line) a
	// git-hook matches on change via flag_changed; jsonb array, NULL/[] = none.
	VerifyHints []string `gorm:"serializer:json;type:jsonb" json:"verify_hints,omitempty"`
	// FlaggedAt/FlagReason: the content/event-driven needs-verification flag, set
	// by verify_hints match or a depends_on change, cleared on re-verify.
	FlaggedAt  *time.Time `json:"flagged_at,omitempty"`
	FlagReason *string    `gorm:"size:500" json:"flag_reason,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`

	Document *Document `gorm:"foreignKey:DocumentID" json:"document,omitempty"`
}

type SlugFormat string

type SubcategoryRule string

type Tenant struct {
	ID   uuid.UUID `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	Name string    `gorm:"size:200;not null;uniqueIndex" json:"name"`

	// Type is a DISPLAY-ONLY classifier ("personal" | "shared") for grouping
	// tenants in the UI. It MUST NOT be read by authorization: internal/authz
	// and authorize/Check never import or inspect this field, and access
	// decisions are identical regardless of its value. New tenants default to
	// "shared"; the NOT NULL DEFAULT backfills existing rows (incl. the default
	// pool) to "shared" on AutoMigrate.
	Type string `gorm:"type:text;not null;default:'shared'" json:"type"`

	// Per-tenant feature toggles. All default to the safest behavior so a tenant
	// upgrading from pre-tightening infra sees no change unless it opts in.
	DuplicateGuard     bool `gorm:"not null;default:false" json:"duplicate_guard"`
	CleanupScanEnabled bool `gorm:"not null;default:false" json:"cleanup_scan_enabled"`
	MetricsEnabled     bool `gorm:"not null;default:false" json:"metrics_enabled"`

	// DuplicateThreshold is the per-tenant near-duplicate cutoff OVERRIDE for the
	// write guard (0<v<=1); NULL inherits the global instance_config default.
	DuplicateThreshold *float64 `gorm:"column:duplicate_threshold" json:"duplicate_threshold"`

	// SelfServicePolicy is the per-tenant override of the global self-service
	// gate: NULL = inherit the global default; else "open" | "admin_only". Set
	// and cleared by system admins only — never self-editable.
	SelfServicePolicy *string `gorm:"column:self_service_policy" json:"self_service_policy"`

	// EffectivePolicy is the resolved self-service policy (override ?? global),
	// computed on read paths — never persisted (gorm:"-").
	EffectivePolicy string `gorm:"-" json:"effective_self_service_policy,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type TenantDefaults struct {
	DuplicateGuard     bool
	CleanupScanEnabled bool
}

type TenantUser struct {
	ID uuid.UUID `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	// Identity anchor: the OIDC (issuer, subject) pair, unique together. Nullable
	// so legacy email-only rows coexist (Postgres treats NULLs as distinct) until
	// they adopt a subject on first login.
	Issuer  *string `gorm:"size:255;uniqueIndex:idx_tenant_users_iss_sub" json:"issuer,omitempty"`
	Subject *string `gorm:"size:255;uniqueIndex:idx_tenant_users_iss_sub" json:"subject,omitempty"`
	// Email is a mutable attribute kept globally unique (one email -> one identity)
	// but no longer the identity key; it refreshes from the claim on login.
	Email    string    `gorm:"size:320;not null;uniqueIndex" json:"email"`
	TenantID uuid.UUID `gorm:"type:uuid;not null;index" json:"tenant_id"`
	Role     string    `gorm:"size:16;not null;default:'member'" json:"role"`

	CreatedAt time.Time `json:"created_at"`

	// Tenant belongsTo — FK on tenant_id with ON DELETE CASCADE.
	Tenant *Tenant `gorm:"foreignKey:TenantID;constraint:OnDelete:CASCADE" json:"-"`
}

type WriteMode string