member-console/internal/domains/querier.go

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

package domains

import (
	"context"
	"database/sql"
	"time"
)

type Querier interface {
	// Soft cap on concurrent external verifications — each is a live 24-hour
	// polling workflow.
	CountPendingClaimsByWorkspace(ctx context.Context, workspaceID string) (int64, error)
	// Re-read under the registry advisory lock before auto-releasing a claim,
	// so a release racing a placement cannot strand a live placement in a
	// released claim (design D3).
	CountPlacementsByClaim(ctx context.Context, claimID string) (int64, error)
	// Callers pass normalized names (trimmed, lowercased, one trailing dot
	// stripped) and the matching label reversal; the registry owns both.
	CreateClaim(ctx context.Context, arg CreateClaimParams) (Claim, error)
	CreatePlacement(ctx context.Context, arg CreatePlacementParams) (Placement, error)
	DeletePlacement(ctx context.Context, placementID string) (int64, error)
	GetClaimByID(ctx context.Context, claimID string) (Claim, error)
	// A pending or active row holds the name (the partial unique index enforces
	// at most one); terminal rows do not block re-claiming.
	GetLiveClaimByRoot(ctx context.Context, rootFqdn string) (Claim, error)
	// Exact-label policy lookup, root-scoped first then global (root_claim_id
	// NULL). A NULL root_claim_id argument matches global rules only, since
	// `root_claim_id = NULL` is never true.
	GetNameRuleForLabel(ctx context.Context, arg GetNameRuleForLabelParams) (NameRule, error)
	// The serving path (/domains/ask). Deliberately unconditional: a row with
	// servable = false is a local refusal, distinct from a registry miss, and
	// the authorizer needs to tell those apart (design D5).
	GetPlacementByFQDN(ctx context.Context, fqdn string) (Placement, error)
	// The release path reads the placement before deleting it: the claim_id it
	// carries is what the auto-release re-count needs.
	GetPlacementByID(ctx context.Context, placementID string) (Placement, error)
	GetPlacementByResource(ctx context.Context, arg GetPlacementByResourceParams) (Placement, error)
	// The abandonment ledger read (design D3): one workspace's abandonments
	// inside a candidate's scope, NEWEST first, capped at the budget.
	//
	// The scope predicate is the scope root AND everything beneath it, so cycling
	// sibling names (a.example.org, b.example.org, …) counts as cycling one name;
	// an ancestor-only or per-name predicate would not close that. Callers pass
	// the budget as the limit: exactly @budget rows back means the budget is
	// exhausted.
	//
	// Newest first, so the LAST row is the entry whose ageing out reopens the
	// scope. Oldest-first would name the globally oldest entry, which is the wrong
	// answer whenever a workspace holds MORE entries than the budget — the pending
	// cap alone lets it bank five against a budget of three, and the member would
	// be told to come back at a time they are still refused. The scope reopens
	// when fewer than @budget entries remain in the window, which is when the
	// @budget-th newest ages out.
	ListAbandonmentsInScope(ctx context.Context, arg ListAbandonmentsInScopeParams) ([]sql.NullTime, error)
	// The operator placements section (ux-ia-naming task 9.1): every exact name
	// actually being served, deployment-wide, each with the provider resource it
	// is wired to. Claims and placements are never conflated
	// (docs/models/domains-registry.md, "Claim vs placement") -- a claim can hold
	// a name that serves nothing, and this is the query that answers what
	// actually serves. Ordered by fqdn so the list reads in the same namespace
	// order as the claims table above it.
	ListAllPlacementsForOperator(ctx context.Context) ([]ListAllPlacementsForOperatorRow, error)
	// The expiry sweep's candidate read (claim-expiry-and-carve-guards D1). This
	// is the query idx_claims_pending_expires_at was created for: the partial
	// index over (expires_at) WHERE status = 'pending' answers it directly, and
	// nothing else in the registry asks a question shaped like it.
	//
	// @deadline is now minus the sweep's grace period, not now. A healthy
	// verification workflow marks its own claim expired within one poll of the
	// deadline and carries the final probe's evidence verdict with it; the sweep
	// carries none, so it must not win that race. Trailing the deadline by more
	// than the poll cap makes the sweep the backstop it is meant to be, for claims
	// whose workflow is gone.
	//
	// Deliberately unlimited: every row a pass finds it makes terminal, so the
	// candidate set drains rather than accumulating.
	ListExpiredPendingClaims(ctx context.Context, deadline time.Time) ([]ListExpiredPendingClaimsRow, error)
	// Ancestor walk: the caller passes the candidate name's suffixes (at most
	// 127) and reads the deepest match. Exact equality keeps this on the
	// live-root unique index.
	ListLiveClaimsByRoots(ctx context.Context, roots []string) ([]Claim, error)
	// The member Domains surface: live claims with the placement count that
	// gates release, counted inline to avoid an N+1 per row.
	ListLiveClaimsByWorkspace(ctx context.Context, workspaceID string) ([]ListLiveClaimsByWorkspaceRow, error)
	// The operator moderation surface (design D7): every live claim in the
	// deployment with the holder attached, pending first and newest first inside
	// each group — a name under contest is a fresh pending claim, so that is the
	// order an operator scans.
	//
	// This is the one query in the stream that reads core (the domains migration
	// grants core_reader to domains_writer for exactly this kind of read). It
	// projects columns rather than whole rows so no core model enters this
	// package's API — sqlc.yaml documents the rename entries a whole-row join
	// would otherwise need.
	ListLiveClaimsForOperator(ctx context.Context) ([]ListLiveClaimsForOperatorRow, error)
	// Descendant scan via the reversed-label prefix ("cafe.wiki" matches
	// "cafe.wiki.alice"). Excludes the subtree root itself — an exact-root
	// collision is the unique index's business.
	ListLiveClaimsInSubtree(ctx context.Context, reversedRoot string) ([]Claim, error)
	ListPlacementsByClaim(ctx context.Context, claimID string) ([]Placement, error)
	// Ancestor walk on placements: an operator placement above a candidate root
	// blocks carving it. Exact equality keeps this on the fqdn unique index.
	ListPlacementsByFQDNs(ctx context.Context, fqdns []string) ([]Placement, error)
	// Descendant scan via the reversed-label prefix; excludes the subtree root
	// itself (an exact hit is the unique index's business).
	ListPlacementsInSubtree(ctx context.Context, reversedRoot string) ([]Placement, error)
	// The breadth budget read (design D5): external claims this workspace started
	// in the rolling window, newest first, capped at the budget. Counted from
	// created_at, so a claim still pending counts exactly like one already given
	// up — the cap bounds how fast a workspace may spray new scopes at all.
	//
	// Newest first for the same reason as ListAbandonmentsInScope: the LAST row is
	// the one whose ageing out reopens the budget, and a workspace can hold more
	// rows than the budget whenever an operator lowers it mid-window.
	//
	// Two kinds of row are NOT initiations and are excluded:
	//
	//   - `expires_at IS NULL` is a grandfathered adoption. Boot reconciliation
	//     writes an active external claim per pre-registry custom domain (design
	//     D8) with no token and no window, so a workspace with ten adopted domains
	//     would otherwise be refused every new claim for a day after each restart.
	//     Every claim a member initiates carries the window it was created with;
	//     no grandfathered claim carries one.
	//   - `system_canceled_at IS NOT NULL` is a claim the console rolled back
	//     because it could not start the verification workflow. D4 is that a
	//     console failure is never charged to the member, and the initiation
	//     budget is a charge.
	ListRecentClaimInitiations(ctx context.Context, arg ListRecentClaimInitiationsParams) ([]time.Time, error)
	// The operator claims ledger section (ux-ia-naming task 9.2): every claim
	// that has left a live state, deployment-wide, newest first. Today only live
	// claims render on the moderation surface; this read makes expired,
	// canceled, and released claims reachable too, in a list segregated from the
	// live one.
	//
	// The three ledger columns ride along unconditionally (not just for external
	// claims) so the handler can decide presentation; blame is read from these
	// columns, never inferred from status (invariant 9 -- status alone says
	// nothing about fault). Capped at 200: this is a page display read, not a
	// business-rule cap like the budget queries above, and terminal rows only
	// accumulate, so an unbounded read would eventually make the section
	// unusable rather than just long.
	ListTerminalClaimsForOperator(ctx context.Context) ([]ListTerminalClaimsForOperatorRow, error)
	// Verification success. Guarded on pending so a late workflow write never
	// reanimates a canceled or expired claim.
	//
	// Proving control wipes this workspace's abandonment slate for the verified
	// name AND ITS OWN SUBTREE (design D3) — deliberately NOT for the wider scope
	// the ledger counts under. The reach is read from the row being activated, so
	// the clear and the activation commit or roll back together.
	//
	// The two widths differ on purpose. Counting by scope is what makes cycling
	// sibling names cost something; clearing by scope would hand that straight
	// back to anyone holding ONE name under a shared root. A workspace that owns
	// attacker.co.uk could burn the co.uk-scoped budget aimed at bakery.co.uk,
	// verify its own name, watch the ledger null out, and cycle forever. Control
	// of one name proves nothing about its siblings, so it clears nothing about
	// them.
	//
	// The two UPDATEs touch disjoint rows: `cleared` only ever matches terminal
	// rows carrying abandoned_at, and the claim being activated is pending, so its
	// abandoned_at is NULL.
	MarkClaimActive(ctx context.Context, claimID string) (int64, error)
	// Member-initiated. Guarded on pending: a cancel that races the active
	// transition loses and updates nothing (design D4).
	//
	// @evidence carries what a fresh cancel-time probe saw (design D5), on the
	// SAME final-probe-decides contract MarkClaimExpired documents above: a
	// member can cancel before any background probe ever ran, so the stored
	// latch alone has nothing to read in that case, and the caller must gather
	// its own evidence immediately before this write. It latches evidence_at on
	// the same COALESCE terms as a probe write, and abandoned_at is stamped only
	// when neither the stored latch nor this final probe found evidence — the
	// evidence-latch parity this comment used to claim without carrying the
	// parameter to back it.
	MarkClaimCanceled(ctx context.Context, arg MarkClaimCanceledParams) (int64, error)
	// Operator moderation (design D7): the terminal write for a force-released
	// PENDING claim. Stamps the ledger unconditionally, where the member-facing
	// cancel exempts a claim carrying evidence — an operator taking a name back is
	// itself the finding that the claim was unwanted, and a squatter who published
	// a decoy challenge record must not buy immunity from moderation with it.
	// Pending-guarded like every other terminal write: a force-release that loses
	// its race to verification updates nothing.
	MarkClaimCanceledForce(ctx context.Context, claimID string) (int64, error)
	// Console-initiated rollback: the claim committed but its verification
	// workflow could not be started, so the name is freed again. Deliberately
	// never stamps abandoned_at — a Temporal outage is not the member's fault and
	// must never debit the ledger (design D4).
	//
	// It stamps system_canceled_at instead, which is the same fact stated
	// positively: the ledger is one budget, and ListRecentClaimInitiations is the
	// other. That one counts every external claim this workspace created, so
	// without a mark on the row an outage during ten attempts would still lock the
	// workspace out for a day — charging the member for the console's failure by a
	// different door.
	MarkClaimCanceledSystem(ctx context.Context, claimID string) (int64, error)
	// The window elapsed with no TXT match. Records an abandonment unless the
	// claim earned the evidence latch (design D3): a member who published our
	// challenge value demonstrably worked on their DNS and is never charged.
	//
	// @evidence carries what the FINAL probe saw, because the latch's usual
	// recovery ("the next probe re-stamps a lost write") has no next probe here:
	// this statement runs immediately after that probe, and a RecordClaimProbe
	// write that failed would otherwise be paid for by the member. It latches
	// evidence_at on the same COALESCE terms as a probe write, so the row an
	// operator reads afterwards says what was actually observed.
	MarkClaimExpired(ctx context.Context, arg MarkClaimExpiredParams) (int64, error)
	// Terminal state for a claim freed after being active (auto-release of an
	// emptied carved claim, or an explicit member release). Guarded on active
	// so it cannot short-circuit a pending verification.
	MarkClaimReleased(ctx context.Context, claimID string) (int64, error)
	// Latest per-record probe result, written by the verification workflow.
	// Guarded on pending so a late probe never touches a terminal row.
	//
	// @evidence latches the first probe that observed OUR challenge value prefix
	// at the challenge name (design D2); the workflow computes it, because only
	// the raw observations distinguish our record from anything else published
	// there. COALESCE makes the latch sticky and the write idempotent, so a lost
	// write is recovered by the next probe.
	RecordClaimProbe(ctx context.Context, arg RecordClaimProbeParams) (int64, error)
	// Provider lifecycle transitions address placements by their own resource
	// identity, not by name (fedwiki: archive => FALSE, restore => TRUE).
	SetPlacementServableByResource(ctx context.Context, arg SetPlacementServableByResourceParams) (int64, error)
}

var _ Querier = (*Queries)(nil)