pg

type CompilationCacheStats struct {
	Hits                    int64
	Misses                  int64
	Coalesced               int64
	Bypasses                int64
	Insertions              int64
	Evictions               int64
	BindingFailures         int64
	BuildFailures           int64
	UnoptimizedCompilations int64
	Size                    int64
	Capacity                int
	Generation              uint64
}

type Config struct {
	// Options controls PostgreSQL transaction isolation and access mode.
	Options pgx.TxOptions

	// QueryExecMode selects pgx's query execution protocol.
	QueryExecMode pgx.QueryExecMode

	// QueryResultFormats selects the PostgreSQL wire format for returned columns.
	QueryResultFormats pgx.QueryResultFormats

	// BatchWriteSize is the number of mutations accumulated before a batch flushes.
	BatchWriteSize int
	// contains filtered or unexported fields
}

type ConnectionCacheStats struct {
	// ID is an opaque provider-assigned identifier for the live connection.
	ID uint64 `json:"id"`

	// Translation reports cache activity scoped to this physical connection.
	Translation TranslationCacheStats `json:"translation"`

	// TraversalWorkspace reports setup state scoped to this physical connection.
	TraversalWorkspace TraversalWorkspaceStats `json:"traversal_workspace"`

	// PreparedStatements reports selected statement warm-up for this connection.
	PreparedStatements PreparedStatementStats `json:"prepared_statements"`
}

type CypherTranslationCache interface {
	TranslateWithPolicy(
		query string,
		graphID int32,
		parameters map[string]any,
		policyIdentity string,
		build func() (translate.Result, string, error),
	) (string, map[string]any, error)
}

type CypherTranslationCacheProvider interface {
	CacheForConnection(conn *pgx.Conn) CypherTranslationCache
}

type Driver struct {
	*SchemaManager
	// contains filtered or unexported fields
}

type DriverOptions struct {
	TranslationCacheEntries int
}

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

type IterationOptions interface {
	Once()
}

type KindMapper interface {
	// MapKindID resolves one PostgreSQL kind identifier to its graph kind.
	MapKindID(ctx context.Context, kindID int16) (graph.Kind, error)

	// MapKindIDs resolves PostgreSQL kind identifiers to their graph kinds.
	MapKindIDs(ctx context.Context, kindIDs []int16) (graph.Kinds, error)

	// MapKind resolves one graph kind to its PostgreSQL identifier.
	MapKind(ctx context.Context, kind graph.Kind) (int16, error)

	// MapKinds resolves graph kinds to their PostgreSQL identifiers.
	MapKinds(ctx context.Context, kinds graph.Kinds) ([]int16, error)

	// AssertKinds creates missing kinds and returns PostgreSQL identifiers for every input kind.
	AssertKinds(ctx context.Context, kinds graph.Kinds) ([]int16, error)
}

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

type LazyStableSnapshotTraversalWorkspaceProvider interface {
	// DeferStableSnapshotTraversalWorkspaces reports whether workspaces may initialize on first use.
	DeferStableSnapshotTraversalWorkspaces() bool
}

type NodeUpdateParameters struct {
	NodeIDs           []graph.ID
	KindSlices        []string
	DeletedKindSlices []string
	Properties        []pgtype.JSONB
	DeletedProperties []string
}

type NodeUpsertParameters struct {
	IDFutures    []*sql.Future[graph.ID]
	KindIDSlices []string
	Properties   []pgtype.JSONB
}

type ParseCacheStats struct {
	// Hits counts lookups served from completed cache entries.
	Hits uint64 `json:"hits"`

	// Misses counts queries parsed by the caller that established a pending entry.
	Misses uint64 `json:"misses"`

	// Bypasses counts queries parsed without retention because caching was unavailable or disallowed.
	Bypasses uint64 `json:"bypasses"`

	// Evictions counts least-recently-used translations removed at capacity.
	Evictions uint64 `json:"evictions"`

	// CoalescedMisses counts callers that waited for an existing parse of the same query.
	CoalescedMisses uint64 `json:"coalesced_misses"`

	// Entries is the number of completed parses retained when the snapshot was taken.
	Entries int `json:"entries"`

	// Pending is the number of in-flight parses when the snapshot was taken.
	Pending int `json:"pending"`

	// Shards is the number of independently locked cache partitions.
	Shards int `json:"shards"`
}

type PoolConfig struct {
	// MinConnections keeps this many idle physical connections available when possible.
	MinConnections int32

	// MaxConnections caps the number of physical PostgreSQL connections.
	MaxConnections int32
}

type PreparedStatementStats struct {
	// Attempts counts requests to prepare selected statements.
	Attempts uint64 `json:"attempts"`

	// Prepared counts statements successfully prepared on a connection.
	Prepared uint64 `json:"prepared"`

	// Reuses counts requests satisfied by an already prepared statement.
	Reuses uint64 `json:"reuses"`

	// Failures counts prepare requests rejected by PostgreSQL.
	Failures uint64 `json:"failures"`

	// Entries is the number of statement identities retained for the connection.
	Entries int `json:"entries"`
}

type QueryHook interface {
	OnStatementMatch(statement string) QueryHookOptions
	OnStatementRegex(re *regexp.Regexp) QueryHookOptions
}

type QueryHookOptions interface {
	Trace() IterationOptions
}

type QueryPathInspector interface {
	Hook() QueryHook
}

type RelationshipUpdateByParameters struct {
	StartIDs   []graph.ID
	EndIDs     []graph.ID
	KindIDs    []int16
	Properties []pgtype.JSONB
}

type RuntimeConfig struct {
	// TranslationCacheEntries is the exact SIEVE entry capacity for each live
	// physical PostgreSQL connection. Zero disables retention.
	TranslationCacheEntries int

	// SharedShortestPathTemplateEntries bounds immutable shortest-path SQL
	// templates shared by V2 physical connections. Zero disables this L2 tier.
	SharedShortestPathTemplateEntries int

	// Pool optionally overrides the v1-compatible connection limits. Nil uses
	// DefaultConfig's limits; a non-nil value must have MaxConnections >= 1
	// and MinConnections <= MaxConnections.
	Pool *PoolConfig
}

type SQLGenerationProfile struct {
	// QueryClass is a low-cardinality category that omits query text and values.
	QueryClass string

	// Parse measures Cypher parsing and parse-cache lookup time.
	Parse time.Duration

	// Graph measures graph-target resolution time.
	Graph time.Duration

	// Policy measures traversal-shape classification and policy selection time.
	Policy time.Duration

	// Cache measures translation-cache lookup and binding time.
	Cache time.Duration

	// Translate measures Cypher-to-SQL translation time on cache misses.
	Translate time.Duration

	// Format measures SQL rendering time after translation.
	Format time.Duration

	// Dispatch measures client-side PostgreSQL query dispatch time.
	Dispatch time.Duration
}

type SQLGenerationProfileCollector interface {
	// RecordSQLGenerationProfile receives a completed query-text-free timing sample.
	RecordSQLGenerationProfile(profile SQLGenerationProfile)
}

type SQLGenerationStats struct {
	// KindLookup counts targeted catalog reads; Dispatch includes their full duration.
	KindLookup SQLGenerationTiming `json:"kind_lookup"`
	// KindRefresh counts full catalog reloads; Dispatch includes their full duration.
	KindRefresh SQLGenerationTiming `json:"kind_refresh"`
	// KindRegistration counts registration operations, including concurrent-insert retries.
	KindRegistration SQLGenerationTiming `json:"kind_registration"`

	// ShortestPath aggregates generation timings for shortest-path queries.
	ShortestPath SQLGenerationTiming `json:"shortest_path"`

	// Other aggregates generation timings for all other queries.
	Other SQLGenerationTiming `json:"other"`
}

type SQLGenerationTiming struct {
	// Count records SQL generation profiles represented by this aggregate.
	Count uint64 `json:"count"`

	// Parse accumulates Cypher parsing time.
	Parse time.Duration `json:"parse"`

	// Graph accumulates graph-resolution time.
	Graph time.Duration `json:"graph"`

	// Policy accumulates traversal-policy selection time.
	Policy time.Duration `json:"policy"`

	// Cache accumulates translation-cache lookup time.
	Cache time.Duration `json:"cache"`

	// Translate accumulates Cypher-to-SQL lowering time.
	Translate time.Duration `json:"translate"`

	// Format accumulates SQL rendering time.
	Format time.Duration `json:"format"`

	// Dispatch accumulates pgx query-dispatch time.
	Dispatch time.Duration `json:"dispatch"`
}

type SQLState string

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

type SharedTemplateStats struct {
	// Hits counts templates served from the shared shortest-path tier.
	Hits uint64 `json:"hits"`

	// Misses counts shared-tier lookups without a retained template.
	Misses uint64 `json:"misses"`

	// Insertions counts templates added to the shared tier.
	Insertions uint64 `json:"insertions"`

	// Evictions counts templates displaced from the shared tier at capacity.
	Evictions uint64 `json:"evictions"`

	// Entries is the shared-tier occupancy at snapshot time.
	Entries int `json:"entries"`

	// Capacity bounds retained templates in the shared tier.
	Capacity int `json:"capacity"`
}

type StableSnapshotTraversalWorkspaceProvider interface {
	// EnsureStableSnapshotTraversalWorkspaces initializes workspaces for conn when required.
	EnsureStableSnapshotTraversalWorkspaces(ctx context.Context, conn *pgxpool.Conn) error
}

type Stats struct {
	// SchemaGeneration partitions state invalidated by schema-sensitive changes.
	SchemaGeneration uint64 `json:"schema_generation"`

	// CapacityPerConnection bounds retained translations for one live connection.
	CapacityPerConnection int `json:"capacity_per_connection"`

	// MinConnections is the configured pgx pool lower connection bound.
	MinConnections int32 `json:"min_connections"`

	// MaxConnections is the configured pgx pool upper connection bound.
	MaxConnections int32 `json:"max_connections"`

	// LiveConnections counts physical connections currently registered by the provider.
	LiveConnections int `json:"live_connections"`

	// RetiredConnections counts connections whose cache state has been closed.
	RetiredConnections uint64 `json:"retired_connections"`

	// Aggregate combines active and retired translation-cache statistics.
	Aggregate TranslationCacheStats `json:"aggregate"`

	// TraversalWorkspace aggregates reusable workspace setup activity.
	TraversalWorkspace TraversalWorkspaceStats `json:"traversal_workspace"`

	// PreparedStatements aggregates selected statement warm-up activity.
	PreparedStatements PreparedStatementStats `json:"prepared_statements"`

	// Connections reports cache state for each currently live physical connection.
	Connections []ConnectionCacheStats `json:"connections"`

	// SQLGeneration aggregates query-text-free SQL generation timings.
	SQLGeneration SQLGenerationStats `json:"sql_generation"`

	// StrategySelection aggregates production routing observations.
	StrategySelection StrategySelectionStats `json:"strategy_selection"`

	// TraversalShapeCache reports bounded structural classifier cache activity.
	TraversalShapeCache TraversalShapeCacheStats `json:"traversal_shape_cache"`

	// TraversalRouteDecision aggregates topology route-decision outcomes.
	TraversalRouteDecision TraversalRouteDecisionStats `json:"traversal_route_decision"`

	// SharedShortestPathTemplates reports the pool-wide immutable template cache.
	SharedShortestPathTemplates SharedTemplateStats `json:"shared_shortest_path_templates"`
}

type StrategySelectionStats struct {
	// Incumbent counts selections that leave the stable executor active.
	Incumbent uint64 `json:"incumbent"`

	// ExactQueryCanary counts candidates selected by exact-query authorization.
	ExactQueryCanary uint64 `json:"exact_query_canary"`

	// StructuralShadow counts structural matches observed without authorization.
	StructuralShadow uint64 `json:"structural_shadow"`

	// StructuralAuthorized counts candidates selected by structural authorization.
	StructuralAuthorized uint64 `json:"structural_authorized"`

	// TopologySelected counts candidates selected by transaction-local topology routing.
	TopologySelected uint64 `json:"topology_selected"`

	// ShapeUnavailable counts queries outside the structural classifier scope.
	ShapeUnavailable uint64 `json:"shape_unavailable"`
}

type SuffixReverseRetryLimits struct {
	// OutputRows caps the number of candidate rows buffered before publication.
	OutputRows int64

	// OutputBytes caps the JSON-encoded size of buffered candidate values.
	OutputBytes int64
}

type SuffixReverseRetryTransaction interface {
	// RawSuffixReverseRetry runs a bounded candidate and, if needed, its exact fallback.
	RawSuffixReverseRetry(candidateSQL, fallbackSQL string, candidateParameters, fallbackParameters map[string]any, limits SuffixReverseRetryLimits) graph.Result
}

type TranslationCacheStats struct {
	// Hits counts translations served from the connection-local cache.
	Hits uint64 `json:"hits"`

	// Misses counts translations not found in the connection-local cache.
	Misses uint64 `json:"misses"`

	// Bypasses counts translations intentionally built without retention.
	Bypasses uint64 `json:"bypasses"`

	// Insertions counts reusable translations published to the local cache.
	Insertions uint64 `json:"insertions"`

	// Evictions counts cached translations displaced at capacity.
	Evictions uint64 `json:"evictions"`

	// BindingFailures counts cache hits that cannot bind current caller values.
	BindingFailures uint64 `json:"binding_failures"`

	// Entries is the local cache occupancy at snapshot time.
	Entries int `json:"entries"`

	// Capacity is the maximum number of retained local translations.
	Capacity int `json:"capacity"`
}

type TraversalPolicy struct {
	// Generation distinguishes policy revisions in cache and rollout identities.
	Generation uint64 `json:"generation"`

	// PromotionManifestSHA256 verifies the immutable promotion manifest supplied below.
	PromotionManifestSHA256 string `json:"promotion_manifest_sha256"`

	// PromotionManifestJSON is the exact verified authorization document. It
	// is intentionally excluded from policy serialization; its digest and
	// content-derived fields form the cache identity.
	PromotionManifestJSON json.RawMessage `json:"-"`
	// QuerySHA256Allowlist is the exact set of query digests authorized by the manifest.
	QuerySHA256Allowlist []string `json:"query_sha256_allowlist"`

	// ShortestPathExecutor selects the manifest-backed shortest-path candidate.
	ShortestPathExecutor optimize.ShortestPathExecutor `json:"shortest_path_executor,omitempty"`

	// EnableExpansionOrientation enables the manifest-backed expansion orientation candidate.
	EnableExpansionOrientation bool `json:"enable_expansion_orientation,omitempty"`
	// EnableTopologyFixedSuffix permits the manifest-v4, snapshot-owned
	// fixed-suffix candidate. It never changes ordinary routing: the
	// transaction route-decision cache must independently select the arm.
	EnableTopologyFixedSuffix bool `json:"enable_topology_fixed_suffix,omitempty"`
	// EnableTopologyFixedSuffixFirstUse permits the manifest-v5 first-use
	// selector. It is deliberately independent of the v4 cache-hit protocol.
	EnableTopologyFixedSuffixFirstUse bool `json:"enable_topology_fixed_suffix_first_use,omitempty"`
	// DisableExpansionOrientation is an evidence-free emergency rollback switch
	// for any manifest-authorized orientation selector.
	DisableExpansionOrientation bool `json:"disable_expansion_orientation,omitempty"`
	// DisableTopologyFixedSuffix is the evidence-free emergency rollback
	// switch for the manifest-v4 fixed-suffix candidate.
	DisableTopologyFixedSuffix bool `json:"disable_topology_fixed_suffix,omitempty"`
	// DisableTopologyFixedSuffixFirstUse is the emergency rollback for v5.
	DisableTopologyFixedSuffixFirstUse bool `json:"disable_topology_fixed_suffix_first_use,omitempty"`
	// DisableEndpointSeededReverse immediately disables the endpoint-seeded reverse candidate.
	DisableEndpointSeededReverse bool `json:"disable_endpoint_seeded_reverse,omitempty"`

	// DisableInlineASPDAG immediately disables the inline ASP DAG candidate.
	DisableInlineASPDAG bool `json:"disable_inline_asp_dag,omitempty"`

	// DisableInlineSPWitness immediately disables the inline shortest-path witness candidate.
	DisableInlineSPWitness bool `json:"disable_inline_sp_witness,omitempty"`
	// DisableInlineSPDistance is the emergency rollback switch for SP-I2-C-D.
	DisableInlineSPDistance bool `json:"disable_inline_sp_distance,omitempty"`
	// contains filtered or unexported fields
}

type TraversalRouteDecision struct {
	// Mode identifies the selected candidate or incumbent arm.
	Mode string `json:"mode"`

	// Reason records the query-text-free rationale for the route decision.
	Reason string `json:"reason"`
}

type TraversalRouteDecisionCollector interface {
	// RecordTraversalRouteDecision receives query-text-free topology routing telemetry.
	RecordTraversalRouteDecision(TraversalRouteDecision)
}

type TraversalRouteDecisionStats struct {
	// Disabled counts queries ineligible for topology routing.
	Disabled uint64 `json:"disabled"`

	// SynopsisUnavailable counts queries without a current graph synopsis.
	SynopsisUnavailable uint64 `json:"synopsis_unavailable"`

	// ShadowMiss counts first observations that populate route-decision shadow state.
	ShadowMiss uint64 `json:"shadow_miss"`

	// ShadowHit counts repeated shadow observations that remain on the incumbent.
	ShadowHit uint64 `json:"shadow_hit"`

	// CandidateHit counts repeated observations that select the candidate route.
	CandidateHit uint64 `json:"candidate_hit"`

	// FirstUseCandidate counts first-use protocol selections of the candidate route.
	FirstUseCandidate uint64 `json:"first_use_candidate"`

	// EstimateRejected counts candidates rejected by the synopsis estimate.
	EstimateRejected uint64 `json:"estimate_rejected"`

	// Capacity counts decisions rejected by bounded transaction-local state.
	Capacity uint64 `json:"capacity"`

	// ParametersInvalid counts queries whose parameters cannot be fingerprinted.
	ParametersInvalid uint64 `json:"parameters_invalid"`
}

type TraversalShape struct {
	// Version identifies the structural-classification schema used for this shape.
	Version string `json:"version"`

	// Family identifies the eligible traversal family.
	Family string `json:"family"`

	// Direction records the traversal's logical direction.
	Direction string `json:"direction"`

	// ObservationMode identifies the semantic observation mode used by the plan.
	ObservationMode string `json:"observation_mode"`

	// MinimumDepth is the inclusive lower bound of the variable expansion.
	MinimumDepth int64 `json:"minimum_depth"`

	// MaximumDepth is the inclusive upper bound of the variable expansion.
	MaximumDepth int64 `json:"maximum_depth"`

	// RelationshipKindCount is the number of relationship kinds constrained by the query.
	RelationshipKindCount int `json:"relationship_kind_count"`

	// UntypedRelationship reports whether the expansion permits any relationship kind.
	UntypedRelationship bool `json:"untyped_relationship"`

	// SuffixLength is the fixed terminal suffix length for fixed-suffix expansions.
	SuffixLength int `json:"suffix_length,omitempty"`

	// CandidateStrategy is the eligible optimizer strategy for this shape.
	CandidateStrategy string `json:"candidate_strategy,omitempty"`

	// Fingerprint is the stable digest of the fields that define this shape.
	Fingerprint string `json:"fingerprint"`
}

type TraversalShapeCacheProvider interface {
	// TraversalShapeFor returns a cached classification or calls classify to produce one.
	TraversalShapeFor(query string, classify func() (TraversalShape, error)) (TraversalShape, error)
}

type TraversalShapeCacheStats struct {
	// Hits counts classifications served from the bounded shape cache.
	Hits uint64 `json:"hits"`

	// Misses counts classifications computed without a retained entry.
	Misses uint64 `json:"misses"`

	// Entries is the number of retained query-digest classifications.
	Entries int `json:"entries"`

	// Capacity bounds retained classifications.
	Capacity int `json:"capacity"`
}

type TraversalStrategySelection struct {
	// Shape is the classified traversal structure considered for selection.
	Shape TraversalShape `json:"shape"`

	// PolicyGeneration identifies the active traversal-policy generation.
	PolicyGeneration uint64 `json:"policy_generation"`

	// SelectorVersion identifies the selection protocol evaluated for the query.
	SelectorVersion string `json:"selector_version"`

	// Candidate names the strategy that could replace the incumbent.
	Candidate string `json:"candidate"`

	// SelectedArm identifies the candidate or incumbent path that was selected.
	SelectedArm string `json:"selected_arm"`

	// Fallback identifies the incumbent strategy used when the candidate is not selected.
	Fallback string `json:"fallback"`

	// Bucket identifies the manifest bucket that authorized the selection, when any.
	Bucket string `json:"bucket,omitempty"`

	// TemplateSHA256 identifies the approved SQL template used by the selected bucket.
	TemplateSHA256 string `json:"template_sha256,omitempty"`

	// Mode identifies the selection mechanism that produced the decision.
	Mode string `json:"mode"`

	// Reason records the query-text-free rationale for the decision.
	Reason string `json:"reason"`
}

type TraversalStrategySelectionCollector interface {
	// RecordTraversalStrategySelection receives query-text-free routing telemetry.
	RecordTraversalStrategySelection(TraversalStrategySelection)
}

type TraversalTopologySynopsis struct {
	// GraphID identifies the graph summarized by this record.
	GraphID int32 `json:"graph_id"`

	// Epoch identifies this atomically published synopsis generation.
	Epoch uint64 `json:"epoch"`

	// SourceMutationEpoch is the graph mutation epoch observed while building the synopsis.
	SourceMutationEpoch uint64 `json:"source_mutation_epoch"`

	// CurrentMutationEpoch is the graph mutation epoch visible when the synopsis was read.
	CurrentMutationEpoch uint64 `json:"current_mutation_epoch"`

	// EstimatorVersion identifies the fixed estimator whose assumptions produced the synopsis.
	EstimatorVersion string `json:"estimator_version"`

	// SchemaVersion identifies the synopsis storage schema used to publish this record.
	SchemaVersion string `json:"schema_version"`

	// Status reports whether publication completed successfully.
	Status string `json:"status"`

	// NodeCount is the graph's node count recorded by the refresh.
	NodeCount int64 `json:"node_count"`

	// EdgeCount is the graph's edge count recorded by the refresh.
	EdgeCount int64 `json:"edge_count"`
}

type TraversalWorkspaceStats struct {
	// Initializations counts successful workspace setup operations.
	Initializations uint64 `json:"initializations"`

	// Reuses counts requests served by a workspace ready in the current generation.
	Reuses uint64 `json:"reuses"`

	// Failures counts workspace setup attempts rejected by PostgreSQL.
	Failures uint64 `json:"failures"`

	// Ready reports whether the workspace is ready for the current schema generation.
	Ready bool `json:"ready"`
}