schema

type AnchorPathStep struct {
	// Type is either "ttu" or "userset"
	Type string

	// For TTU patterns (e.g., "viewer from parent"):
	// LinkingRelation is "parent" (the relation that links to the parent object)
	// TargetType is the first parent object type found with an anchor (e.g., "folder")
	// TargetRelation is the relation to check on the parent (e.g., "viewer")
	// AllTargetTypes contains ALL object types that the linking relation can point to
	// when each type has the target relation with direct grants. This is used for
	// generating UNION queries when parent can be multiple types (e.g., [document, folder]).
	// RecursiveTypes contains object types where the target relation is recursive
	// (same type as the object type being checked). These require check_permission_internal
	// instead of list function composition to handle the recursion correctly.
	LinkingRelation string
	TargetType      string
	TargetRelation  string
	AllTargetTypes  []string
	RecursiveTypes  []string

	// For userset patterns (e.g., [group#member]):
	// SubjectType is "group"
	// SubjectRelation is "member"
	SubjectType     string
	SubjectRelation string
}

type AuthzModel struct {
	ID               int64
	ObjectType       string  // Object type this rule applies to
	Relation         string  // Relation this rule defines
	SubjectType      *string // Allowed subject type (for direct rules)
	ImpliedBy        *string // Implying relation (for role hierarchy)
	ParentRelation   *string // Parent relation to check (for inheritance)
	ExcludedRelation *string // Relation to exclude (for "but not" rules)
	SubjectWildcard  *bool   // Whether wildcard subjects are allowed for SubjectType
	// Excluded parent relation for tuple-to-userset exclusions.
	ExcludedParentRelation *string // Parent relation to exclude (for "but not rel from parent")
	ExcludedParentType     *string // Linking relation for the excluded parent relation
	// New fields for userset references and intersection support
	SubjectRelation       *string // For userset refs [type#relation]: the relation part
	RuleGroupID           *int64  // Groups rules that form an intersection
	RuleGroupMode         *string // RuleGroupModeIntersection or RuleGroupModeExcludeIntersection
	CheckRelation         *string // For intersection: which relation to check
	CheckExcludedRelation *string // For intersection: exclusion on check_relation (e.g., "editor but not owner")
	CheckParentRelation   *string // For intersection: parent relation to check (tuple-to-userset)
	CheckParentType       *string // For intersection: linking relation on current object
}

type CheckFunctionData struct {
	ObjectType   string // The authorization object type (e.g., "document", "folder")
	Relation     string // The relation name (e.g., "viewer", "editor")
	FunctionName string // The generated function name (e.g., "check_document_viewer")
	// InternalCheckFunctionName is the dispatcher internal function name to call
	// for recursive or complex checks.
	InternalCheckFunctionName string
	FeaturesString            string // Human-readable list of enabled features for SQL comments
	ClosureValues             string // Inline SQL VALUES for closure lookups, eliminates JOIN
	UsersetValues             string // Inline SQL VALUES for userset patterns, eliminates JOIN

	// Feature flags
	HasDirect       bool
	HasImplied      bool
	HasWildcard     bool
	HasUserset      bool
	HasRecursive    bool
	HasExclusion    bool
	HasIntersection bool

	// HasStandaloneAccess is true if the relation has access paths outside of intersections.
	// When false and HasIntersection is true, the only access is through intersection groups.
	// For example, "viewer: [user] and writer" has NO standalone access - the [user] is
	// inside the intersection. But "viewer: [user] or (writer and editor)" HAS standalone
	// access via the [user] path.
	HasStandaloneAccess bool

	// Pre-rendered SQL fragments
	DirectCheck    string // Pre-rendered SQL EXISTS for direct tuple lookup
	UsersetCheck   string // Pre-rendered SQL EXISTS for userset membership checks
	ExclusionCheck string // Pre-rendered SQL EXISTS for exclusion (denial) checks
	AccessChecks   string // All access paths OR'd together for the final permission decision

	// For recursive (TTU) patterns
	ParentRelations []ParentRelationData // TTU patterns: parent object relations to check recursively

	// For implied relations that need function calls
	ImpliedFunctionCalls []ImpliedFunctionCall // Complex closure relations requiring function calls

	// For intersection patterns - each group is AND'd, groups are OR'd
	IntersectionGroups []IntersectionGroupData // AND groups where all parts must be satisfied
}

type ClosureRow struct {
	ObjectType         string
	Relation           string
	SatisfyingRelation string
	ViaPath            []string // For debugging: path from relation to satisfying_relation
}

type ComplexExclusionCheckData struct {
	ObjectType                string
	ExcludedRelation          string
	InternalCheckFunctionName string
}

type ComplexUsersetCheckData struct {
	ObjectType      string
	Relation        string
	SubjectType     string
	SubjectRelation string

	InternalCheckFunctionName string
}

type DirectCheckData struct {
	ObjectType        string
	RelationList      string
	SubjectTypeFilter string // e.g., "'user', 'employee'" - allowed subject types
	SubjectIDCheck    string
}

type DispatcherCase struct {
	ObjectType        string
	Relation          string
	CheckFunctionName string
}

type DispatcherData struct {
	FunctionName            string
	HasSpecializedFunctions bool
	Cases                   []DispatcherCase
}

type ExclusionCheckData struct {
	ObjectType       string
	ExcludedRelation string
	SubjectIDCheck   string
}

type Execer interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

type GenerateConfig struct {
	// Package name for generated code. Default: "authz"
	Package string

	// RelationPrefixFilter is a prefix filter for relation names.
	// Only relations with this prefix will have constants generated.
	// If empty, all relations will be generated.
	//
	// Example: "can_" generates only permission relations, omitting roles.
	RelationPrefixFilter string

	// IDType specifies the type to use for object IDs.
	// Default: "string"
	// The type must implement fmt.Stringer or be safely convertible to string.
	//
	// Common values: "string", "int64", "uuid.UUID"
	// The generated code uses fmt.Sprint(id) for conversion.
	IDType string
}

type GeneratedSQL struct {
	// Functions contains CREATE OR REPLACE FUNCTION statements
	// for each specialized check function.
	Functions []string
	// NoWildcardFunctions contains CREATE OR REPLACE FUNCTION statements
	// for no-wildcard variants of each specialized check function.
	NoWildcardFunctions []string

	// Dispatcher contains the check_permission dispatcher function
	// that routes to specialized functions.
	Dispatcher string

	// DispatcherNoWildcard contains the check_permission_no_wildcard dispatcher.
	DispatcherNoWildcard string
}

type ImpliedFunctionCall struct {
	FunctionName string // Function to call for this implied relation (e.g., "check_document_editor")
}

type IndirectAnchorInfo struct {
	// Path describes the traversal from this relation to the anchor.
	// For "document.viewer: viewer from folder" where folder.viewer: [user],
	// Path would contain one TTU step pointing to folder.viewer.
	// For multi-hop chains, Path contains multiple steps.
	Path []AnchorPathStep

	// AnchorType and AnchorRelation identify the relation with direct grants.
	// This is the final destination of the path - a relation that has HasDirect.
	AnchorType     string
	AnchorRelation string
}

type InlineSQLData struct {
	// ClosureValues contains tuples of (object_type, relation, satisfying_relation).
	ClosureValues string
	// UsersetValues contains tuples of (object_type, relation, subject_type, subject_relation).
	UsersetValues string
}

type IntersectionExclusionCheckData struct {
	ObjectType string
	Parts      []string // Relations that must ALL be satisfied for exclusion to apply
}

type IntersectionGroup struct {
	Relations       []string              // Relations that must all be satisfied (AND)
	ParentRelations []ParentRelationCheck // Parent inheritance checks (tuple-to-userset)
	Exclusions      map[string][]string   // Per-relation exclusions: relation -> list of excluded relations
}

type IntersectionGroupData struct {
	Parts []IntersectionPartData // Individual checks within this AND group
}

type IntersectionGroupInfo struct {
	Parts []IntersectionPart
}

type IntersectionPart struct {
	IsThis           bool                // [user] - direct assignment check on the same relation
	HasWildcard      bool                // For IsThis parts: whether direct assignment allows wildcards
	Relation         string              // Relation to check
	ExcludedRelation string              // For nested exclusions like "editor but not owner"
	ParentRelation   *ParentRelationInfo // For tuple-to-userset in intersection
}

type IntersectionPartData struct {
	// FunctionName is the check function to call (e.g., "check_document_writer")
	FunctionName string

	// IsThis is true if this part is a self-reference ([user] pattern)
	// When true, we check for a direct tuple on the relation being defined
	IsThis bool

	// ThisHasWildcard is true if this "This" part allows wildcard tuples.
	// This is only relevant when IsThis is true. It reflects whether the relation's
	// own direct subject types allow wildcards, NOT whether the relation's overall
	// HasWildcard flag is set (which may include wildcards from closure relations).
	ThisHasWildcard bool

	// HasExclusion is true if this part has a nested exclusion (e.g., "editor but not owner")
	HasExclusion bool

	// ExcludedRelation is the relation to exclude (for nested exclusions)
	ExcludedRelation string

	// IsTTU is true if this part is a tuple-to-userset pattern
	IsTTU bool

	// TTULinkingRelation is the linking relation for TTU patterns (e.g., "parent")
	TTULinkingRelation string

	// TTURelation is the relation to check on the parent for TTU patterns
	TTURelation string
}

type ListAnchorPathStepData struct {
	Type string // "ttu" or "userset"

	// For TTU steps (e.g., "viewer from parent"):
	LinkingRelation string   // "parent"
	TargetType      string   // "folder" (first type with direct anchor)
	TargetRelation  string   // "viewer"
	AllTargetTypes  []string // All types with direct anchor (e.g., ["document", "folder"])
	RecursiveTypes  []string // Types needing check_permission_internal (same-type recursive TTU)

	// For userset steps (e.g., [group#member]):
	SubjectType             string // "group"
	SubjectRelation         string // "member"
	SatisfyingRelationsList string // SQL-formatted satisfying relations
	HasWildcard             bool   // Whether membership allows wildcards
}

type ListDispatcherCase struct {
	ObjectType   string
	Relation     string
	FunctionName string
}

type ListDispatcherData struct {
	// HasSpecializedFunctions is true if any specialized list functions were generated.
	HasSpecializedFunctions bool

	// Cases contains the routing cases for specialized functions.
	Cases []ListDispatcherCase
}

type ListGeneratedSQL struct {
	// ListObjectsFunctions contains CREATE OR REPLACE FUNCTION statements
	// for each specialized list_objects function (list_{type}_{relation}_objects).
	ListObjectsFunctions []string

	// ListSubjectsFunctions contains CREATE OR REPLACE FUNCTION statements
	// for each specialized list_subjects function (list_{type}_{relation}_subjects).
	ListSubjectsFunctions []string

	// ListObjectsDispatcher contains the list_accessible_objects dispatcher function
	// that routes to specialized functions or falls back to generic.
	ListObjectsDispatcher string

	// ListSubjectsDispatcher contains the list_accessible_subjects dispatcher function
	// that routes to specialized functions or falls back to generic.
	ListSubjectsDispatcher string
}

type ListIndirectAnchorData struct {
	// Path steps from this relation to the anchor
	Path []ListAnchorPathStepData

	// First step's target function (used for composition)
	// For multi-hop chains, we compose with the first step's target, not the anchor.
	// e.g., for job.can_read -> permission.assignee -> role.assignee, we call
	// list_permission_assignee_objects (first step's target), not list_role_assignee_objects (anchor).
	FirstStepTargetFunctionName string // e.g., "list_permission_assignee_objects"

	// Anchor relation info (end of the chain)
	AnchorType              string // Type of anchor relation (e.g., "folder")
	AnchorRelation          string // Anchor relation name (e.g., "viewer")
	AnchorFunctionName      string // Name of anchor's list function (e.g., "list_folder_viewer_objects")
	AnchorSubjectTypes      string // SQL-formatted allowed subject types from anchor
	AnchorHasWildcard       bool   // Whether anchor supports wildcards
	SatisfyingRelationsList string // SQL-formatted list of relations that satisfy the anchor
}

type ListObjectsFunctionData struct {
	ObjectType     string
	Relation       string
	FunctionName   string
	FeaturesString string
	ClosureValues  string

	// MaxUsersetDepth is the maximum userset chain depth reachable from this relation.
	// Used by depth-exceeded template to report the actual depth in error messages.
	MaxUsersetDepth int

	// ExceedsDepthLimit is true if MaxUsersetDepth >= 25.
	// Routes to depth-exceeded template which immediately raises M2002.
	ExceedsDepthLimit bool

	// RelationList is a SQL-formatted list of simple closure relations to check.
	// e.g., "'viewer', 'editor', 'owner'" - only relations that can use tuple lookup
	RelationList string

	// ComplexClosureRelations are closure relations that need check_permission_internal.
	// These have exclusions or other complex features that can't be resolved via tuple lookup.
	ComplexClosureRelations []string

	// IntersectionClosureRelations are closure relations that have intersection patterns
	// and are list-generatable. These need to be composed with their list function.
	IntersectionClosureRelations []string

	// SubjectIDCheck is the SQL fragment for checking subject_id with wildcard support.
	// e.g., "(t.subject_id = p_subject_id OR t.subject_id = '*')"
	SubjectIDCheck string

	// AllowedSubjectTypes is a SQL-formatted list of allowed subject types.
	// e.g., "'user', 'employee'" - used to enforce model type restrictions.
	AllowedSubjectTypes string

	// Exclusion-related fields (Phase 3)
	HasExclusion bool // true if this relation has exclusion patterns

	// SimpleExcludedRelations are excluded relations that can use direct tuple lookup.
	// These are relations without userset, TTU, exclusion, intersection, or implied closure.
	SimpleExcludedRelations []string

	// ComplexExcludedRelations are excluded relations that need check_permission_internal.
	// These have userset, TTU, intersection, exclusion, or implied closure.
	ComplexExcludedRelations []string

	// ExcludedParentRelations are TTU exclusions like "but not viewer from parent".
	ExcludedParentRelations []ParentRelationInfo

	// ExcludedIntersectionGroups are intersection exclusions like "but not (editor and owner)".
	ExcludedIntersectionGroups []IntersectionGroupInfo

	// Userset-related fields (Phase 4)
	HasUserset      bool                     // true if this relation has userset patterns
	UsersetPatterns []ListUsersetPatternData // [group#member] patterns for UNION expansion

	// TTU/Recursive-related fields (Phase 5)
	ParentRelations []ListParentRelationData // TTU patterns like "viewer from parent"

	// SelfReferentialLinkingRelations is a SQL-formatted list of linking relations
	// from self-referential TTU patterns. Used for depth checking in recursive CTE.
	// e.g., "'parent', 'folder'" when there are TTU patterns viewer from parent, viewer from folder
	SelfReferentialLinkingRelations string

	// Intersection-related fields (Phase 6)
	HasIntersection     bool                    // true if this relation has intersection patterns
	IntersectionGroups  []IntersectionGroupInfo // Intersection groups for list functions
	HasStandaloneAccess bool                    // true if there are access paths outside intersections

	// Phase 8: Indirect anchor for composed access patterns
	HasIndirectAnchor bool                    // true if access is via indirect anchor
	IndirectAnchor    *ListIndirectAnchorData // Anchor info for composed templates

	// Phase 9B: Self-referential userset patterns
	HasSelfReferentialUserset bool // true if any userset pattern references same type/relation
}

type ListParentRelationData struct {
	Relation            string // Relation to check on parent (e.g., "viewer")
	LinkingRelation     string // Relation that links to parent (e.g., "parent")
	AllowedLinkingTypes string // SQL-formatted list of parent types (e.g., "'folder', 'org'")
	ParentType          string // First allowed linking type (for self-referential check)
	IsSelfReferential   bool   // True if any parent type equals the object type

	// CrossTypeLinkingTypes is a SQL-formatted list of linking types that are NOT self-referential.
	// When a parent relation allows both self-referential and cross-type links (e.g., [folder, document]
	// for document.parent), this contains only the cross-type entries (e.g., "'folder'").
	// Used to generate check_permission_internal calls for cross-type parents even when
	// IsSelfReferential is true for the same linking relation.
	CrossTypeLinkingTypes string
	HasCrossTypeLinks     bool // True if CrossTypeLinkingTypes is non-empty
}

type ListSubjectsFunctionData struct {
	ObjectType     string
	Relation       string
	FunctionName   string
	FeaturesString string
	ClosureValues  string

	// MaxUsersetDepth is the maximum userset chain depth reachable from this relation.
	// Used by depth-exceeded template to report the actual depth in error messages.
	MaxUsersetDepth int

	// ExceedsDepthLimit is true if MaxUsersetDepth >= 25.
	// Routes to depth-exceeded template which immediately raises M2002.
	ExceedsDepthLimit bool

	// RelationList is a SQL-formatted list of simple closure relations to check.
	RelationList string

	// AllSatisfyingRelations is a SQL-formatted list of ALL relations that satisfy this relation.
	// Includes both simple and complex closure relations. Used by userset filter case.
	// e.g., "'can_view', 'viewer'" when viewer implies can_view
	AllSatisfyingRelations string

	// ComplexClosureRelations are closure relations that need check_permission_internal.
	ComplexClosureRelations []string

	// IntersectionClosureRelations are closure relations that have intersection patterns
	// and are list-generatable. These need to be composed with their list function.
	IntersectionClosureRelations []string

	// AllowedSubjectTypes is a SQL-formatted list of allowed subject types.
	// e.g., "'user', 'employee'" - used to enforce model type restrictions.
	AllowedSubjectTypes string

	// HasWildcard is true if the model allows wildcard subjects.
	// When false, wildcard tuples (subject_id = '*') should be excluded from results.
	HasWildcard bool

	// Exclusion-related fields (Phase 3)
	HasExclusion bool // true if this relation has exclusion patterns

	// SimpleExcludedRelations are excluded relations that can use direct tuple lookup.
	SimpleExcludedRelations []string

	// ComplexExcludedRelations are excluded relations that need check_permission_internal.
	ComplexExcludedRelations []string

	// ExcludedParentRelations are TTU exclusions like "but not viewer from parent".
	ExcludedParentRelations []ParentRelationInfo

	// ExcludedIntersectionGroups are intersection exclusions like "but not (editor and owner)".
	ExcludedIntersectionGroups []IntersectionGroupInfo

	// Userset-related fields (Phase 4)
	HasUserset      bool                     // true if this relation has userset patterns
	UsersetPatterns []ListUsersetPatternData // [group#member] patterns for expansion

	// TTU/Recursive-related fields (Phase 5)
	ParentRelations []ListParentRelationData // TTU patterns like "viewer from parent"

	// Intersection-related fields (Phase 6)
	HasIntersection    bool                    // true if this relation has intersection patterns
	IntersectionGroups []IntersectionGroupInfo // Intersection groups for list functions

	// Phase 8: Indirect anchor for composed access patterns
	HasIndirectAnchor bool                    // true if access is via indirect anchor
	IndirectAnchor    *ListIndirectAnchorData // Anchor info for composed templates

	// Phase 9B: Self-referential userset patterns
	HasSelfReferentialUserset bool // true if any userset pattern references same type/relation
}

type ListUsersetPatternData struct {
	SubjectType     string // e.g., "group"
	SubjectRelation string // e.g., "member"

	// SatisfyingRelationsList is a SQL-formatted list of relations that satisfy SubjectRelation.
	// e.g., "'member', 'admin'" when admin implies member.
	SatisfyingRelationsList string

	// SourceRelationList is a SQL-formatted list of relations to search for userset grant tuples.
	// For direct userset patterns, this is the same as the parent's RelationList.
	// For closure userset patterns (inherited from implied relations), this is the source relation.
	// e.g., "'viewer'" for a pattern inherited from viewer: [group#member]
	SourceRelationList string

	// SourceRelation is the relation where this userset pattern is defined (unquoted).
	// Used for closure patterns to verify permission via check_permission_internal.
	SourceRelation string

	// IsClosurePattern is true if this pattern is inherited from an implied relation.
	// When true, candidates need to be verified via check_permission_internal on the
	// source relation to apply any exclusions or complex features.
	IsClosurePattern bool

	// HasWildcard is true if any satisfying relation allows wildcards.
	// When true, membership check includes subject_id = '*'.
	HasWildcard bool

	// IsComplex is true if this pattern requires check_permission_internal for membership.
	// This happens when any relation in the closure has TTU, exclusion, or intersection.
	IsComplex bool

	// IsSelfReferential is true if SubjectType == ObjectType and SubjectRelation == Relation.
	// Self-referential usersets (e.g., group.member: [group#member]) require recursive CTEs.
	// Non-self-referential usersets use JOIN-based expansion.
	IsSelfReferential bool
}

type MigrateOptions struct {
	// DryRun outputs SQL to the provided writer without applying changes to the database.
	// If nil, migration proceeds normally. Use for previewing migrations or generating migration scripts.
	DryRun io.Writer

	// Force re-runs migration even if schema/codegen unchanged. Use when manually fixing corrupted state or testing.
	Force bool

	// SchemaContent is the raw schema text used for checksum calculation to detect schema changes.
	// If empty, skip-if-unchanged optimization is disabled.
	SchemaContent string
}

type MigrationRecord struct {
	SchemaChecksum string
	CodegenVersion string
	FunctionNames  []string
}

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

type ParentRelationCheck struct {
	Relation        string // Relation to check on the parent object (e.g., "viewer")
	LinkingRelation string // Relation that links to the parent object (e.g., "parent")
}

type ParentRelationData struct {
	LinkingRelation     string // Relation linking to parent object (e.g., "parent" in "viewer from parent")
	ParentRelation      string // Relation to verify on parent (e.g., "viewer" in "viewer from parent")
	AllowedLinkingTypes string // SQL-formatted list of allowed parent types (e.g., "'folder', 'org'")
}

type ParentRelationInfo struct {
	Relation            string   // Relation to check on parent (e.g., "viewer")
	LinkingRelation     string   // Relation that links to parent (e.g., "parent")
	AllowedLinkingTypes []string // Types allowed for linking relation (e.g., ["folder", "org"])
}

type RelationAnalysis struct {
	ObjectType string           // The object type (e.g., "document")
	Relation   string           // The relation name (e.g., "viewer")
	Features   RelationFeatures // Feature flags determining what SQL to generate

	// CanGenerate is true if this relation can use generated SQL for check.
	// This is computed by checking both the relation's own features AND
	// ensuring all relations in the satisfying closure are simply resolvable.
	// Set by ComputeCanGenerate after all relations are analyzed.
	CanGenerate bool

	// CannotGenerateReason explains why CanGenerate is false.
	// Empty when CanGenerate is true.
	CannotGenerateReason string

	// CanGenerateListValue is true if this relation can use generated SQL for list functions.
	// List functions have stricter requirements than check functions because they use
	// set operations (UNION, EXCEPT) rather than boolean composition.
	// Set by ComputeCanGenerate after all relations are analyzed.
	CanGenerateListValue bool

	// CannotGenerateListReason explains why CanGenerateListValue is false.
	// Empty when CanGenerateListValue is true.
	CannotGenerateListReason string

	// For Direct/Implied patterns - from closure table
	SatisfyingRelations []string // Relations that satisfy this one (e.g., ["viewer", "editor", "owner"])

	// For Exclusion patterns
	ExcludedRelations []string // Relations to exclude (for simple "but not X" patterns)

	// SimpleExcludedRelations are excluded relations that can be checked with
	// a direct tuple lookup (no userset, TTU, exclusion, or intersection).
	SimpleExcludedRelations []string

	// ComplexExcludedRelations are excluded relations that need function calls
	// (have userset, TTU, exclusion, intersection, or implied closure).
	// The generated code will call check_permission_internal for these.
	ComplexExcludedRelations []string

	// ExcludedParentRelations captures "but not X from Y" patterns (TTU exclusions).
	// These are resolved by looking up the linking relation Y and calling
	// check_permission_internal for relation X on each linked object.
	ExcludedParentRelations []ParentRelationInfo

	// ExcludedIntersectionGroups captures "but not (A and B)" patterns.
	// These are resolved by ANDing together check_permission_internal calls
	// for each relation in the group.
	ExcludedIntersectionGroups []IntersectionGroupInfo

	// For Userset patterns
	UsersetPatterns []UsersetPattern // [group#member] patterns

	// For Recursive patterns (tuple-to-userset)
	ParentRelations []ParentRelationInfo

	// For Intersection patterns
	IntersectionGroups []IntersectionGroupInfo

	// HasComplexUsersetPatterns is true if any userset pattern is complex
	// (requires check_permission_internal call). When true, the generated
	// function needs PL/pgSQL with cycle detection.
	HasComplexUsersetPatterns bool

	// Direct subject types (for generating direct tuple checks)
	DirectSubjectTypes []string // e.g., ["user", "org"]

	// AllowedSubjectTypes is the union of all subject types from satisfying relations.
	// This is used to enforce type restrictions in generated SQL.
	// Computed by ComputeCanGenerate.
	AllowedSubjectTypes []string

	// SimpleClosureRelations contains relations in the closure that can use tuple lookup.
	// These are relations without exclusions, usersets, recursion, or intersections.
	// Computed by ComputeCanGenerate.
	SimpleClosureRelations []string

	// ComplexClosureRelations contains relations in the closure that need function calls.
	// These are relations with exclusions that are themselves generatable.
	// Computed by ComputeCanGenerate.
	ComplexClosureRelations []string

	// IntersectionClosureRelations contains relations in the closure that have intersection
	// patterns and are list-generatable. These need to be handled by composing with their
	// list function rather than tuple lookup (since intersection relations have no tuples).
	// Computed by computeCanGenerateList.
	IntersectionClosureRelations []string

	// ClosureUsersetPatterns contains userset patterns from closure relations.
	// For example, if `can_view: viewer` and `viewer: [group#member]`, then
	// can_view's ClosureUsersetPatterns includes group#member.
	// This is used by list functions to expand usersets from implied relations.
	// Computed by ComputeCanGenerate.
	ClosureUsersetPatterns []UsersetPattern

	// ClosureParentRelations contains TTU patterns from closure relations.
	// For example, if `can_view: viewer` and `viewer: viewer from parent`, then
	// can_view's ClosureParentRelations includes the parent relation info.
	// This is used by list functions to traverse TTU paths from implied relations.
	// Computed by ComputeCanGenerate.
	ClosureParentRelations []ParentRelationInfo

	// ClosureExcludedRelations contains excluded relations from closure relations.
	// For example, if `can_read: reader` and `reader: [user] but not restricted`,
	// then can_read's ClosureExcludedRelations includes "restricted".
	// This ensures exclusions are applied when accessing through implied relations.
	// Computed by ComputeCanGenerate.
	ClosureExcludedRelations []string

	// IndirectAnchor describes how to reach a relation with direct grants when this
	// relation has no direct/implied access paths. For pure TTU or pure userset patterns,
	// this traces through the pattern to find an anchor relation with [user] or similar.
	// Nil if the relation has direct/implied access or if no anchor can be found.
	// Computed by ComputeCanGenerate via findIndirectAnchor.
	IndirectAnchor *IndirectAnchorInfo

	// MaxUsersetDepth is the maximum userset chain depth reachable from this relation.
	// -1 means infinite (self-referential userset cycle), 0 means no userset patterns.
	// Values >= 25 indicate the relation will always exceed the depth limit.
	// Computed by ComputeCanGenerate via computeMaxUsersetDepth.
	MaxUsersetDepth int

	// ExceedsDepthLimit is true if MaxUsersetDepth >= 25.
	// These relations generate functions that immediately raise M2002.
	ExceedsDepthLimit bool

	// SelfReferentialUsersets lists userset patterns that reference the same type and relation.
	// e.g., for group.member: [user, group#member], this would contain
	// UsersetPattern{SubjectType: "group", SubjectRelation: "member"}
	// These patterns require recursive CTEs to expand nested group membership.
	// Computed by ComputeCanGenerate.
	SelfReferentialUsersets []UsersetPattern

	// HasSelfReferentialUserset is true if len(SelfReferentialUsersets) > 0.
	// When true, the list templates use recursive CTEs to expand the userset chain.
	HasSelfReferentialUserset bool
}

type RelationDefinition struct {
	Name              string   // Relation name: "owner", "can_read", etc.
	ImpliedBy         []string // Relations that imply this one: ["owner", "admin"]
	ParentRelations   []ParentRelationCheck
	ExcludedRelations []string // For nested exclusions: "(a but not b) but not c" -> ["b", "c"]
	// ExcludedParentRelations captures tuple-to-userset exclusions like "but not viewer from parent".
	ExcludedParentRelations []ParentRelationCheck
	// ExcludedIntersectionGroups captures exclusions that require ALL relations in a group.
	// For "viewer: writer but not (editor and owner)", this is [[editor, owner]].
	ExcludedIntersectionGroups []IntersectionGroup
	// SubjectTypeRefs provides detailed subject type info including userset relations.
	// For [user, group#member], this would contain:
	//   - {Type: "user", Relation: ""}
	//   - {Type: "group", Relation: "member"}
	SubjectTypeRefs []SubjectTypeRef
	// IntersectionGroups contains groups of relations that must ALL be satisfied.
	// Each group is an AND (intersection), multiple groups are OR'd together.
	// For "viewer: writer and editor", IntersectionGroups = [["writer", "editor"]]
	// For "viewer: (a and b) or (c and d)", IntersectionGroups = [["a","b"], ["c","d"]]
	IntersectionGroups []IntersectionGroup
}

type RelationFeatures struct {
	HasDirect       bool // [user] - direct tuple lookup, the relation accepts specific subject types
	HasImplied      bool // viewer: editor - this relation is satisfied by another relation via closure
	HasWildcard     bool // [user:*] - allows wildcard grants that match any subject_id
	HasUserset      bool // [group#member] - grants via membership in another object's relation
	HasRecursive    bool // viewer from parent - grants inherited through parent/child relationships (TTU)
	HasExclusion    bool // but not blocked - denies access based on negative conditions
	HasIntersection bool // writer and editor - requires AND of all parts
}

type Status struct {
	// SchemaExists indicates if the schema.fga file exists on disk.
	SchemaExists bool

	// TuplesExists indicates if the melange_tuples relation exists (view, table, or materialized view).
	// This must be created by the user to map their domain tables.
	TuplesExists bool
}

type SubjectTypeRef struct {
	Type     string // Subject type: "user", "group", etc.
	Relation string // For userset refs: the relation (e.g., "member" in [group#member])
	Wildcard bool   // True if this is a wildcard reference (user:*)
}

type TTUExclusionCheckData struct {
	ObjectType                string
	ExcludedRelation          string // The relation to check on the parent (e.g., "viewer")
	LinkingRelation           string // The linking relation (e.g., "parent")
	AllowedLinkingTypes       string // SQL-formatted list of allowed parent types (e.g., "'folder', 'org'")
	InternalCheckFunctionName string
}

type TypeDefinition struct {
	Name      string
	Relations []RelationDefinition
}

type UsersetCheckData struct {
	ObjectType      string
	Relation        string
	SubjectType     string
	SubjectRelation string

	// SatisfyingRelationsList is a SQL-formatted list of relations that satisfy SubjectRelation.
	// For example: "'member_c4', 'member_c3', 'member_c2', 'member_c1', 'member'"
	SatisfyingRelationsList string

	// HasWildcard is true if the subject relation supports wildcards.
	// When true, the membership check should also match subject_id = '*'.
	HasWildcard bool

	InternalCheckFunctionName string
}

type UsersetPattern struct {
	SubjectType     string // e.g., "group"
	SubjectRelation string // e.g., "member"

	// SatisfyingRelations contains all relations in the closure of SubjectRelation.
	// For example, if SubjectRelation="member_c4" and member_c4 is implied by member,
	// this would contain ["member_c4", "member_c3", "member_c2", "member_c1", "member"].
	// This is populated by ComputeCanGenerate from the closure data.
	SatisfyingRelations []string

	// SourceRelation is the relation where this userset pattern is defined.
	// For direct patterns, this is the same as the relation being analyzed.
	// For closure patterns (inherited from implied relations), this is the source relation.
	// e.g., for can_view: viewer where viewer: [group#member], SourceRelation="viewer"
	// This is used by list functions to search for grant tuples in the correct relation.
	SourceRelation string

	// HasWildcard is true if any relation in the closure supports wildcards.
	// When true, the userset check should match membership tuples with subject_id = '*'.
	// This is populated by ComputeCanGenerate from the subject relation's features.
	HasWildcard bool

	// IsComplex is true if any relation in the closure is not closure-compatible
	// (has userset, TTU, exclusion, or intersection). When true, the userset check
	// must call check_permission_internal to verify membership instead of using
	// a simple tuple JOIN.
	// This is populated by ComputeCanGenerate.
	IsComplex bool
}

type UsersetRule struct {
	ObjectType                string
	Relation                  string
	TupleRelation             string
	SubjectType               string
	SubjectRelation           string
	SubjectRelationSatisfying string
}