// Code generated by sqlc. DO NOT EDIT.
// versions:
//   sqlc v1.31.1

package db

import (
	"context"

	"github.com/google/uuid"
	"github.com/jackc/pgx/v5/pgtype"
)

type Querier interface {
	// Keeps the channel IATA filter in step with packet retention.
	DeleteOldChannelIATAs(ctx context.Context, lastHeard pgtype.Timestamptz) error
	// Deletes nodes not seen since the given cutoff. node_iatas and node_neighbors cascade-
	// delete via FK. Excludes nodes referenced by observer_owners.owner_node_id -- that FK has
	// no ON DELETE action, so deleting one directly would fail the whole statement anyway, and
	// an operator manually recorded ownership for that node, so leave it alone even if stale.
	// known_routes.node_ids is a plain UUID[] with no FK; a deleted node's id can be left
	// dangling in old routes there, but ReconfirmTask already prunes stale/ambiguous routes
	// periodically and will clean those up on its own schedule.
	DeleteOldNodes(ctx context.Context, lastSeen pgtype.Timestamptz) error
	// Opt-in age-out: preserve retained history and manually recorded ownership.
	// Bound deletions per cleanup tick and skip observers being updated by ingest.
	DeleteOldObservers(ctx context.Context, lastSeen pgtype.Timestamptz) ([]uuid.UUID, error)
	// Deletes packets and their observations older than the given cutoff.
	// packet_observations cascade-delete via FK.
	DeleteOldPackets(ctx context.Context, lastHeardAt pgtype.Timestamptz) error
	// Deletes routes not observed since the retention cutoff ($1), and rarely-observed
	// routes (observation_count < $2) not observed since the grace cutoff ($3).
	DeleteOldRoutes(ctx context.Context, arg DeleteOldRoutesParams) error
	// Deletes telemetry rows older than the given cutoff. Called by the cleanup goroutine.
	DeleteOldTelemetry(ctx context.Context, reportedAt pgtype.Timestamptz) error
	// Keeps the trace IATA filter in step with packet retention.
	DeleteOldTraceIATAs(ctx context.Context, lastHeard pgtype.Timestamptz) error
	GetChannelByID(ctx context.Context, id int32) (Channel, error)
	// Returns neighbors of a node that are in a different IATA.
	GetCrossIATANeighbors(ctx context.Context, arg GetCrossIATANeighborsParams) ([]GetCrossIATANeighborsRow, error)
	GetHourlyStats(ctx context.Context, arg GetHourlyStatsParams) ([]MvHourlyIataStat, error)
	GetIATA(ctx context.Context, iata string) (IataCode, error)
	// border is NULL when the IATA exists but has no border configured; a
	// missing row (unknown IATA) is sql.ErrNoRows, same not-found distinction
	// GetIATA already makes.
	GetIATABorder(ctx context.Context, iata string) ([]byte, error)
	GetKnownRoutesByNode(ctx context.Context, arg GetKnownRoutesByNodeParams) ([]GetKnownRoutesByNodeRow, error)
	GetNodeByID(ctx context.Context, id uuid.UUID) (GetNodeByIDRow, error)
	GetNodeByPubkey(ctx context.Context, publicKey []byte) (uuid.UUID, error)
	// Returns the neighbors of a node with details, ordered by most recently seen.
	GetNodeNeighbors(ctx context.Context, nodeID uuid.UUID) ([]GetNodeNeighborsRow, error)
	GetNodesByIDs(ctx context.Context, dollar_1 []uuid.UUID) ([]GetNodesByIDsRow, error)
	GetObserverBrokers(ctx context.Context, observerID uuid.UUID) ([]GetObserverBrokersRow, error)
	GetObserverByID(ctx context.Context, id uuid.UUID) (Observer, error)
	GetObserverByPubkey(ctx context.Context, publicKey []byte) (Observer, error)
	GetObserverLastIATA(ctx context.Context, observerID uuid.UUID) (string, error)
	GetObserverRadio(ctx context.Context, id uuid.UUID) (GetObserverRadioRow, error)
	GetObserverScopes(ctx context.Context, observerID uuid.UUID) ([]string, error)
	GetObserverTelemetry(ctx context.Context, arg GetObserverTelemetryParams) ([]GetObserverTelemetryRow, error)
	GetObserverTelemetryBucketed(ctx context.Context, arg GetObserverTelemetryBucketedParams) ([]GetObserverTelemetryBucketedRow, error)
	GetPacketByHash(ctx context.Context, packetHash []byte) (GetPacketByHashRow, error)
	GetPacketObservationCount(ctx context.Context, packetHash []byte) (int64, error)
	// Return distinct observation IATAs in first-heard order for path resolution,
	// without fetching full observations separately for every trace packet.
	GetPacketsByTraceTag(ctx context.Context, decode string) ([]GetPacketsByTraceTagRow, error)
	GetRadioPresets(ctx context.Context, arg GetRadioPresetsParams) ([]MvRadioPreset, error)
	GetRegion(ctx context.Context, id int32) (GetRegionRow, error)
	GetRegionBySlug(ctx context.Context, slug string) (GetRegionBySlugRow, error)
	GetRegionIATAs(ctx context.Context, regionID int32) ([]string, error)
	GetScopeByName(ctx context.Context, name string) (GetScopeByNameRow, error)
	GetScopeNames(ctx context.Context) ([]string, error)
	// Count each table on its own; the old cross-join blew up to millions of rows
	// before COUNT(DISTINCT) (~10s).
	GetScopeStats(ctx context.Context) ([]GetScopeStatsRow, error)
	GetScopesByIATAs(ctx context.Context, dollar_1 []string) ([]GetScopesByIATAsRow, error)
	// Repeaters/room servers (node_type 2/3) whose current advert-derived clock drift exceeds
	// the given threshold in magnitude, worst first. Not time-windowed -- reflects each node's
	// latest measured drift, not an aggregate over a period.
	// Select the filtered page before aggregating its IATA memberships.
	GetStatsClockDrift(ctx context.Context, arg GetStatsClockDriftParams) ([]GetStatsClockDriftRow, error)
	// Returns node counts grouped by type, optionally filtered by IATA.
	GetStatsNodeTypes(ctx context.Context, dollar_1 []string) ([]GetStatsNodeTypesRow, error)
	// ============================================================
	// STATS
	// ============================================================
	GetStatsOverview(ctx context.Context, dollar_1 []string) (GetStatsOverviewRow, error)
	// Payload-type counts for the IATA within the window, summed from the
	// precomputed hourly buckets.
	GetStatsPayloadBreakdown(ctx context.Context, arg GetStatsPayloadBreakdownParams) ([]GetStatsPayloadBreakdownRow, error)
	// Top N advertisers in the window, summed from the hourly buckets.
	GetStatsTopAdvertisers(ctx context.Context, arg GetStatsTopAdvertisersParams) ([]GetStatsTopAdvertisersRow, error)
	// Top N observers for the IATA within the window, summed from the precomputed
	// hourly buckets. Counts sum across matched IATAs; iata is a representative one.
	GetStatsTopObservers(ctx context.Context, arg GetStatsTopObserversParams) ([]GetStatsTopObserversRow, error)
	// Top N talkers (by decrypted sender_name) in the window, summed from the hourly buckets.
	GetStatsTopTalkers(ctx context.Context, arg GetStatsTopTalkersParams) ([]GetStatsTopTalkersRow, error)
	GetTopNodes(ctx context.Context, arg GetTopNodesParams) ([]MvTopNodesByIatum, error)
	GetTransportScopeByName(ctx context.Context, name string) (int32, error)
	GetTransportScopes(ctx context.Context) ([]GetTransportScopesRow, error)
	// ============================================================
	// CHANNEL MESSAGES
	// ============================================================
	InsertChannelMessage(ctx context.Context, arg InsertChannelMessageParams) (int64, error)
	// ============================================================
	// PACKET OBSERVATIONS
	// ============================================================
	InsertObservation(ctx context.Context, arg InsertObservationParams) (PacketObservation, error)
	// Inserts a telemetry snapshot for an observer. The reported_at timestamp should
	// be truncated to the configured resolution before calling to ensure deduplication.
	InsertObserverTelemetry(ctx context.Context, arg InsertObserverTelemetryParams) error
	// Returns all messages across all channels with optional time, IATA, scope and cursor filters.
	// Pass empty string for iata or scope to skip those filters.
	// Pass cursor=0 to start from the beginning.
	ListAllChannelMessages(ctx context.Context, arg ListAllChannelMessagesParams) ([]ListAllChannelMessagesRow, error)
	// Returns messages for a channel identified by integer ID.
	// Pass a zero/null timestamp for since to return all messages up to limit.
	// Pass empty string for iata to skip IATA filtering.
	// Pass cursor=0 to start from the beginning.
	ListChannelMessages(ctx context.Context, arg ListChannelMessagesParams) ([]ListChannelMessagesRow, error)
	// Returns messages for all channels matching a hash byte.
	// May return messages from multiple channels if the hash collides across different keys.
	// Pass empty string for iata or scope to skip those filters.
	// Pass cursor=0 to start from the beginning.
	ListChannelMessagesByHash(ctx context.Context, arg ListChannelMessagesByHashParams) ([]ListChannelMessagesByHashRow, error)
	// Channels ordered by last seen, optionally filtered by hash and/or IATAs
	// (membership via channel_iatas). NULL hash / empty array skip those filters.
	// Pass cursor=0 to start from the beginning (cursor is last_seen epoch ms).
	ListChannels(ctx context.Context, arg ListChannelsParams) ([]Channel, error)
	ListIATAs(ctx context.Context) ([]IataCode, error)
	// Only one branch runs. Keep the IATA range ordered by the composite index:
	// generic plans can otherwise prefer scanning the global timestamp index.
	// The text equality preserves exact input matching, including trailing spaces.
	ListKnownRoutes(ctx context.Context, arg ListKnownRoutesParams) ([]ListKnownRoutesRow, error)
	// Returns messages after the given message ID, ordered oldest first.
	// Used for WS reconnect backfill.
	ListMessagesAfterID(ctx context.Context, arg ListMessagesAfterIDParams) ([]ListMessagesAfterIDRow, error)
	ListNodeObservations(ctx context.Context, arg ListNodeObservationsParams) ([]ListNodeObservationsRow, error)
	// Limit the filtered node page before enriching IATA membership and neighbours.
	ListNodes(ctx context.Context, arg ListNodesParams) ([]ListNodesRow, error)
	ListObservationsForPacket(ctx context.Context, packetHash []byte) ([]ListObservationsForPacketRow, error)
	// Returns advert packets (payload_type=4) heard by a specific observer.
	// Pass cursor=0 to start from the beginning, or the last seen id for pagination.
	ListObserverAdverts(ctx context.Context, arg ListObserverAdvertsParams) ([]ListObserverAdvertsRow, error)
	// Pass cursor=0 to start from the beginning, or the last seen observer's rownum for pagination.
	// Note: observers use UUID PKs so we order by last_seen and use a keyset on last_seen+id.
	ListObservers(ctx context.Context, arg ListObserversParams) ([]ListObserversRow, error)
	// Returns packets with the latest observation rolled in for display.
	// Pass cursor=0 to start from the beginning. IATA-filtered requests are
	// served by ListPacketsByIATAs instead.
	ListPackets(ctx context.Context, arg ListPacketsParams) ([]ListPacketsRow, error)
	// Returns packets with observations after the given observation ID, ordered oldest first.
	// Used for WS reconnect backfill. Pass afterObservationId=0 to start from the beginning.
	ListPacketsAfterID(ctx context.Context, arg ListPacketsAfterIDParams) ([]ListPacketsAfterIDRow, error)
	// IATA-filtered packet list, driven from idx_observations_iata_heard.
	// Walking packets newest-first and probing for the site probes ~589k packets
	// to fill a page for a quiet site; walking the site's own observation log is
	// proportional to the page size instead. Results are ordered by when the
	// requested sites heard the packet (site-local recency) and the cursor
	// follows that ordering. scan_depth caps how deep each site's observation
	// log is walked. A packet repeats once per observer that heard it, so a
	// page can collapse to fewer distinct packets than were asked for without
	// the site being exhausted. scan_saturated reports whether any site hit
	// that cap and scan_floor the oldest heard_at they all cover, so a short
	// page can keep paging instead of reading as the end of the data.
	// A site that filled scan_depth still has unread history below its floor.
	// The newest such floor is the point above which every site is covered.
	ListPacketsByIATAs(ctx context.Context, arg ListPacketsByIATAsParams) ([]ListPacketsByIATAsRow, error)
	// ============================================================
	// REGIONS
	// ============================================================
	ListRegions(ctx context.Context) ([]ListRegionsRow, error)
	// ============================================================
	// TRACES
	// ============================================================
	// Returns distinct trace tags with summary info, ordered by most recent first.
	// IATA membership comes from trace_iatas (joining observations here spilled the
	// hash join). Per-tag details filled in only for the returned page.
	ListTraceTags(ctx context.Context, arg ListTraceTagsParams) ([]ListTraceTagsRow, error)
	// Returns GRP_TXT packets (payload_type=5) never successfully decrypted. Used at boot to
	// retry decryption against the current keystore for packets whose channel key was only added
	// to the config after they'd already been ingested -- see
	// internal/ingest.BackfillChannelMessages.
	ListUndecryptedGroupTextPackets(ctx context.Context) ([]ListUndecryptedGroupTextPacketsRow, error)
	// Delete node_neighbors where the neighbor has departed from node_short_ids
	// for that IATA, or where its prefix_4 is now ambiguous.
	ReconfirmNeighbors(ctx context.Context) error
	// Checks the $1 least-recently-reconfirmed routes: deletes those with a departed
	// hop node or a hop prefix now matching >1 node in that IATA (length-aware:
	// 1/2/3/4-byte hop prefixes check prefix_1/2/3/4), and stamps the survivors.
	ReconfirmRoutes(ctx context.Context, limit int32) error
	RefreshHourlyStats(ctx context.Context) error
	RefreshPayloadBreakdown(ctx context.Context) error
	RefreshRadioPresets(ctx context.Context) error
	RefreshTopAdvertisers(ctx context.Context) error
	RefreshTopNodes(ctx context.Context) error
	RefreshTopObservers(ctx context.Context) error
	RefreshTopTalkers(ctx context.Context) error
	// Logical endpoints can be any advertised role, unlike intermediate relay hops.
	// Endpoint hashes are always one byte; use the existing (iata, prefix_1) index.
	// LIMIT 1 keeps generic plans on a node PK lookup per candidate instead of
	// flattening the join into a scan of all nodes. The PK already guarantees one row.
	ResolveEndpointHashes(ctx context.Context, arg ResolveEndpointHashesParams) ([]ResolveEndpointHashesRow, error)
	// ============================================================
	// HELPERS
	// ============================================================
	// Path hash resolution is split per prefix width so each query gets a
	// cacheable generic plan on its (iata, prefix_N) index; a single CASE
	// predicate forced a fresh custom plan on every call.
	ResolvePathHashesP1(ctx context.Context, arg ResolvePathHashesP1Params) ([]ResolvePathHashesP1Row, error)
	ResolvePathHashesP2(ctx context.Context, arg ResolvePathHashesP2Params) ([]ResolvePathHashesP2Row, error)
	ResolvePathHashesP3(ctx context.Context, arg ResolvePathHashesP3Params) ([]ResolvePathHashesP3Row, error)
	ResolvePathHashesP4(ctx context.Context, arg ResolvePathHashesP4Params) ([]ResolvePathHashesP4Row, error)
	// Returns known routes containing a subsequence from source to destination hash prefix.
	// Verifies source appears before destination in the route.
	SearchKnownRoutes(ctx context.Context, arg SearchKnownRoutesParams) ([]SearchKnownRoutesRow, error)
	SetNodeDefaultScope(ctx context.Context, arg SetNodeDefaultScopeParams) error
	SetNodeMultibytePaths(ctx context.Context, id uuid.UUID) error
	SetNodeMultibyteTraces(ctx context.Context, id uuid.UUID) error
	SetPacketDecrypted(ctx context.Context, packetHash []byte) error
	TouchObserverBrokers(ctx context.Context, arg TouchObserverBrokersParams) error
	// Batched flush of coalesced presence bumps. GREATEST keeps a late flush
	// from regressing a newer write-through (e.g. a status update).
	TouchObservers(ctx context.Context, arg TouchObserversParams) error
	TouchPackets(ctx context.Context, arg TouchPacketsParams) error
	// Records the observer's own OTA-reported region scope, from the "self"
	// field of a /neighbors report. Always known (not queried OTA), so this
	// unconditionally overwrites, unlike the neighbor-side region_scope.
	UpdateObserverRegionScope(ctx context.Context, arg UpdateObserverRegionScopeParams) error
	UpdateObserverStatus(ctx context.Context, arg UpdateObserverStatusParams) (uuid.UUID, error)
	// ============================================================
	// CHANNELS
	// ============================================================
	// Upsert a channel by (hash, key_fingerprint). Pass NULL fingerprint for
	// hash-only records (key unknown). Returns the channel row.
	UpsertChannel(ctx context.Context, arg UpsertChannelParams) (Channel, error)
	UpsertChannelHashOnly(ctx context.Context, channelHash []byte) (int32, error)
	// Refreshes at most hourly so repeat hears don't churn the row.
	UpsertChannelIATA(ctx context.Context, arg UpsertChannelIATAParams) error
	// Copyright 2026 Beacon Contributors
	// SPDX-License-Identifier: agpl
	// ============================================================
	// IATA CODES
	// ============================================================
	UpsertIATA(ctx context.Context, iata string) error
	// Written by the config-file-driven seeder (internal/config/seed.go), not a
	// runtime HTTP path. border is a full, pre-validated GeoJSON Feature with
	// bbox already computed -- see internal/config/border.go.
	UpsertIATABorder(ctx context.Context, arg UpsertIATABorderParams) error
	UpsertIATADetails(ctx context.Context, arg UpsertIATADetailsParams) error
	// ============================================================
	// ROUTES
	// ============================================================
	// Route identity is path_key, an md5 of node_ids computed by the caller.
	// On conflict, observation_count and last_seen are bumped.
	UpsertKnownRoute(ctx context.Context, arg UpsertKnownRouteParams) error
	// ============================================================
	// NODES
	// ============================================================
	UpsertNode(ctx context.Context, arg UpsertNodeParams) (Node, error)
	// ============================================================
	// NODE IATAS
	// ============================================================
	UpsertNodeIATA(ctx context.Context, arg UpsertNodeIATAParams) error
	// ============================================================
	// NEIGHBORS
	// ============================================================
	// Records or updates a neighbor relationship between two nodes observed in the same IATA.
	// node_id is the advertising node, neighbor_id is the first-hop forwarder.
	// snr is optional; pass NULL when no signal reading is available (the
	// common case). regionScope is optional too; pass NULL whenever the OTA
	// scope query for this neighbor didn't succeed (status != "responded"),
	// so a failed/timed-out query doesn't erase a previously known scope.
	// On conflict, snr and region_scope are only overwritten when a new
	// non-null value is supplied.
	UpsertNodeNeighbor(ctx context.Context, arg UpsertNodeNeighborParams) error
	UpsertNodeShortID(ctx context.Context, arg UpsertNodeShortIDParams) error
	// ============================================================
	// OBSERVERS
	// ============================================================
	UpsertObserver(ctx context.Context, publicKey []byte) (Observer, error)
	// ============================================================
	// OBSERVER BROKERS
	// ============================================================
	UpsertObserverBroker(ctx context.Context, arg UpsertObserverBrokerParams) error
	UpsertObserverScope(ctx context.Context, arg UpsertObserverScopeParams) error
	// ============================================================
	// PACKETS
	// ============================================================
	UpsertPacket(ctx context.Context, arg UpsertPacketParams) (UpsertPacketRow, error)
	UpsertRegion(ctx context.Context, arg UpsertRegionParams) (int32, error)
	UpsertRegionIATA(ctx context.Context, arg UpsertRegionIATAParams) error
	// Refreshes at most hourly so repeat hears don't churn the row.
	UpsertTraceIATA(ctx context.Context, arg UpsertTraceIATAParams) error
	// ============================================================
	// TRANSPORT CODES
	// ============================================================
	UpsertTransportScope(ctx context.Context, arg UpsertTransportScopeParams) error
}

var _ Querier = (*Queries)(nil)
