ir

type API struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
	// BasePath is the prefix every route sits under, for example "/api/v1".
	BasePath string `json:"base_path"`

	// Revision is the date this API surface last changed, as YYYY-MM-DD.
	//
	// It is not a build stamp and not [Version]: Version is the path segment,
	// and a build stamp would move on every regeneration, so two identical
	// clients built a month apart would look a month apart. This moves only
	// when the document's own hash does, which is what makes "how old is the
	// oldest client still calling" a question with an answer.
	//
	// Empty for a document nobody stamped — [Document.Hash] deliberately does
	// not see this field, so stamping one never changes the other.
	Revision string `json:"revision,omitempty"`

	// RevisionHeader is the header Revision travels in, both ways.
	//
	// Configurable because it is a name in somebody else's namespace: a proxy
	// or a gateway may already have claimed it. Empty in a document that
	// predates the setting; a generator reading it falls back to the default.
	RevisionHeader string `json:"revision_header,omitempty"`

	Enums     []Enum     `json:"enums"`
	Objects   []Object   `json:"objects"`
	Resources []Resource `json:"resources"`

	// Auth is the authentication foundation this API is served with, or nil for
	// a project that has none.
	//
	// It is here rather than beside the schema because it is part of the surface:
	// the endpoints it mounts, the permissions a caller has to hold, and how long
	// a token a client is holding stays valid are all things a specification and a
	// client library have to say. A generator reads it instead of asking the
	// project what was configured, which is what keeps the wiring, the document
	// and the client from each carrying their own copy of the answer.
	Auth *Auth `json:"auth,omitempty"`

	// Files is the file handling this API is served with, or nil for a project
	// that accepts no uploads.
	//
	// Here for the reason [API.Auth] is: a byte cap, a sweep interval and the
	// list of types served inline are all part of the surface, and a generator
	// reads them out of the document rather than asking the project what was
	// configured. That is what keeps the wiring, the documentation and a
	// client's expectations from each carrying their own copy of the answer.
	Files *Files `json:"files,omitempty"`

	// Notifications is the inbox this API serves, or nil for a project with
	// none. Here for the reason [API.Auth] and [API.Files] are.
	Notifications *Notifications `json:"notifications,omitempty"`

	// Presence is the resolved `presence:` block, or nil for a project that does
	// not track it.
	Presence *Presence `json:"presence,omitempty"`

	// Throttle is the resolved `throttle:` block, or nil for a project that
	// does not limit API calls.
	//
	// It is part of the surface rather than a deployment detail, which is why it
	// is here and not beside the database settings: the numbers travel to
	// clients in the RateLimit-* headers and into the generated documentation,
	// so a specification that quoted anything else would be quoting a number
	// nobody enforces.
	Throttle *Throttle `json:"throttle,omitempty"`

	// Cache is the resolved `cache:` block, or nil for a project that caches
	// nothing.
	//
	// It is the one part of this document no client can observe, which is why
	// [Document.Hash] clears it: whether a replica answered a request out of
	// memory or out of the database is invisible over HTTP, and a project that
	// spent a revision turning it on would be telling every client it was built
	// against something older than the server.
	Cache *Cache `json:"cache,omitempty"`

	// Servers are the deployments this API is served on, in the order the project
	// named them.
	//
	// Here for the reason [API.Auth] is: the OpenAPI document, the Go client and
	// the TypeScript client each have to say where the API is, and a generator
	// reading it out of the document is what keeps the three from carrying their
	// own copies of the answer. A language added later gets the deployments
	// without growing an option of its own.
	//
	// Empty for a project that has named none, which is the honest state for an
	// API that is not deployed anywhere yet: the document then describes a
	// relative server and the clients ask their caller for a URL.
	//
	// Order is meaningful — a documentation viewer sends its trial request to the
	// first entry — so nothing between here and an emitter sorts it.
	Servers []Server `json:"servers,omitempty"`

	// Web is where this API's browser front end is served, or nil for a project
	// that has no such thing.
	//
	// A deployment fact like [API.Servers], and here for the same reason: two
	// generators read it and neither owns it. The server generator turns it into
	// the origin a provider sign-in redirects to and the origins a preflight is
	// answered for — one fact, two answers that must not disagree.
	//
	// Nil is the switch. No web block means no cross-origin code emitted at all,
	// which is the state every project that serves its front end from the same
	// origin should stay in.
	Web *Web `json:"web,omitempty"`

	// Tracing is the spans this API's generated code opens, or nil for a
	// project that asked for none.
	//
	// Nil is the question every generator asks, and asking it is the whole
	// mechanism: a nil here means no import of rig/observe, no span, and no
	// OpenTelemetry in the application's go.mod. Not a span that calls a no-op
	// — optional, in rig, means absent.
	Tracing *Tracing `json:"tracing,omitempty"`

	// Monitoring is rig's own page over the spans, or nil for a project that
	// asked for none. Never set without Tracing.
	Monitoring *Monitoring `json:"monitoring,omitempty"`

	// OpenAPI is where this API serves the document describing it, or nil for a
	// project that leaves the document a file.
	//
	// Here rather than in the openapi generator's options for the reason
	// [API.Auth] is: two generators have to agree about it. The server mounts the
	// routes and the document has to describe them, and a specification that
	// omitted the routes it is fetched over would be the one omission this
	// generator cannot excuse.
	OpenAPI *OpenAPI `json:"openapi,omitempty"`

	// EmbeddedFoundation says rig's own migrations are carried by the modules
	// that own them rather than vendored into this project's migrations
	// directory.
	//
	// It is here because a generator has to know. The application applies its
	// own schema, so a project whose modules carry theirs needs the code that
	// hands those sets to rig/migrate in the right order — and a project that
	// vendored them must not get it, because then the same DDL would be applied
	// twice under two histories.
	//
	// A bool rather than the mode's spelling: vendored is the default and the
	// absence, so false is what a document written before the key existed means.
	EmbeddedFoundation bool `json:"embedded_foundation,omitempty"`

	// Permissions is every permission this API's endpoints require, computed once
	// at Freeze from the endpoints themselves.
	//
	// Derived once rather than by each consumer, for the same reason
	// [Endpoint.Pattern] is: the handler's check, the catalogue written to the
	// database, an administration screen and the grant an owner receives all have
	// to mean the same thing, and three places deriving it is three places to
	// drift.
	Permissions []Permission `json:"permissions"`
}

type AuditColumns struct {
	CreatedAt *ColumnRef `json:"created_at,omitempty"`
	CreatedBy *ColumnRef `json:"created_by,omitempty"`
	UpdatedAt *ColumnRef `json:"updated_at,omitempty"`
	UpdatedBy *ColumnRef `json:"updated_by,omitempty"`
	DeletedAt *ColumnRef `json:"deleted_at,omitempty"`
	DeletedBy *ColumnRef `json:"deleted_by,omitempty"`

	// The key columns record which API key a change came through, where the
	// account columns record whose account it was. An integration's service
	// account may be shared between several keys, so the pair together say both
	// "the nightly import did this" and "through this credential".
	CreatedByAPIKey *ColumnRef `json:"created_by_api_key,omitempty"`
	UpdatedByAPIKey *ColumnRef `json:"updated_by_api_key,omitempty"`
	DeletedByAPIKey *ColumnRef `json:"deleted_by_api_key,omitempty"`
}

type Auth struct {
	// BasePath is the prefix the endpoints sit under, for example "/auth".
	BasePath string `json:"base_path"`

	Tenant  AuthTenant  `json:"tenant"`
	Session AuthSession `json:"session"`
	// EmailCode is the mailed-code sign-in. It is a value rather than a pointer
	// because Enabled already carries the off state, and a nil would make every
	// consumer nil-check before reading one bool.
	EmailCode AuthEmailCode `json:"email_code"`
	Limits    AuthLimits    `json:"limits"`

	// AllowTenantCreation mounts POST <base>/tenants, where somebody signed in
	// makes one and becomes its owner.
	AllowTenantCreation bool `json:"allow_tenant_creation"`
	// RequireVerifiedEmail refuses a sign-in until the address is verified.
	RequireVerifiedEmail bool `json:"require_verified_email"`

	// AllowedIdentityDomains are the domains a stranger's address must be in to
	// become a person here. Empty, which is the default, restricts nobody.
	//
	// omitempty, so that a project without one leaves the document exactly as it
	// was — this key arriving would otherwise rewrite every golden IR for a
	// setting none of them uses.
	AllowedIdentityDomains []string `json:"allowed_identity_domains,omitempty"`

	// TrustedProxies are the CIDR ranges whose X-Forwarded-For may be believed.
	// Empty means none, and an address is then read from the connection.
	TrustedProxies []string `json:"trusted_proxies,omitempty"`

	// LogRetention is how long an authentication log entry is kept. Zero keeps
	// everything, which is the default because nothing prunes the table unless a
	// project says to.
	//
	// It is never shorter than the longest window in Limits: those limits are
	// counted from this table, so a shorter window would delete the rows a
	// lockout is adding up to. The configuration refuses one rather than clamping
	// it, and the server refuses to start on one assembled by hand.
	LogRetention Duration `json:"log_retention,omitempty"`

	// OAuth is nil when no provider sign-in is configured, which is also when
	// the provider routes do not exist.
	OAuth *AuthOAuth `json:"oauth,omitempty"`
}

type AuthEmailCode struct {
	// Enabled mounts POST <base>/email-code and POST <base>/email-code/verify.
	Enabled bool `json:"enabled"`
	// Length is how many digits the code has.
	Length int `json:"length"`
	// TTL is how long a code lasts.
	TTL Duration `json:"ttl"`
	// MaxAttempts is how many wrong guesses kill one code. It is a ceiling on
	// the code rather than a rate limit on the address, which is why it is here
	// and not in AuthLimits.
	MaxAttempts int `json:"max_attempts"`
	// AllowProvisioning sends a code to an address rig has never seen, creating
	// the person. Off means a code goes only to an address that already has an
	// identity.
	AllowProvisioning bool `json:"allow_provisioning"`
}

type AuthLimit struct {
	Max    int      `json:"max"`
	Window Duration `json:"window"`
}

type AuthLimits struct {
	// LoginByEmail locks one account after a handful of wrong codes.
	LoginByEmail AuthLimit `json:"login_by_email"`
	// LoginByIP throttles one source spraying many accounts. It is deliberately
	// looser than the address limit, so an office behind one NAT does not trip it.
	LoginByIP AuthLimit `json:"login_by_ip"`
	// EmailCodeRequest bounds codes mailed per address, and EmailCodeByIP bounds
	// them per source across every address — which is what limits identity
	// creation when AuthEmailCode.AllowProvisioning is set.
	EmailCodeRequest   AuthLimit `json:"email_code_request"`
	EmailCodeByIP      AuthLimit `json:"email_code_ip"`
	VerificationResend AuthLimit `json:"verification_resend"`
	// Refresh bounds one session's rotations.
	Refresh        AuthLimit `json:"refresh"`
	APIKeyFailures AuthLimit `json:"api_key_failures"`
	// InvitationPreview bounds reading an invitation link per source. It is the
	// one unauthenticated endpoint keyed by a secret rather than an address.
	InvitationPreview AuthLimit `json:"invitation_preview"`
}

type AuthOAuth struct {
	// BaseURL is this application's own origin, which the callback URL is built
	// from and which the provider has registered exactly.
	BaseURL string `json:"base_url,omitempty"`
	// BaseURLEnv names an environment variable that overrides BaseURL, for the
	// ordinary case where the origin differs per deployment.
	BaseURLEnv string `json:"base_url_env,omitempty"`
	// OriginFromHost derives the origin per request from the Host instead, which
	// is what an application serving a tenant per subdomain needs: the state
	// cookie is set on the host the sign-in started at, and a browser will not
	// send it to a sibling.
	OriginFromHost bool `json:"origin_from_host,omitempty"`

	// SigningKeyEnv names the environment variable holding the key that signs
	// the state parameter. A generated key works for one process and fails
	// across replicas, since a callback may land on a different one.
	SigningKeyEnv string `json:"signing_key_env,omitempty"`

	// StateTTL bounds how long a sign-in round trip may take.
	StateTTL Duration `json:"state_ttl"`

	// AllowProvisioning creates an identity the first time somebody signs in
	// with a provider. Off means a provider sign-in only works for an address
	// that already has one.
	AllowProvisioning bool `json:"allow_provisioning"`
	// AllowJoining creates an account in the tenant a sign-in named, for
	// somebody not in it yet. Resolved: the configuration's key is tri-state
	// and defaults to AllowProvisioning, and that default is applied before it
	// reaches here.
	AllowJoining bool `json:"allow_joining"`
	// AllowedReturnTo bounds where a finished sign-in may land. An open redirect
	// is the classic mistake here.
	AllowedReturnTo []string `json:"allowed_return_to,omitempty"`
	// Insecure allows the state cookie over plain HTTP, for local development
	// where a browser would refuse the __Host- prefixed one.
	Insecure bool `json:"insecure,omitempty"`

	Providers []AuthProvider `json:"providers"`
}

type AuthProvider struct {
	// Name is one of [ProviderGoogle], [ProviderMicrosoft], [ProviderGitHub].
	// It is also the route segment: <base>/oauth/google/start.
	Name string `json:"name"`

	ClientIDEnv     string `json:"client_id_env"`
	ClientSecretEnv string `json:"client_secret_env"`
	// TenantEnv is Microsoft's own idea of a tenant, which has nothing to do
	// with rig's: "common" accepts any account, a directory id restricts sign-in
	// to one organization.
	TenantEnv string `json:"tenant_env,omitempty"`

	// Required fails startup when the credentials are absent. The default skips
	// the provider instead, so one deployment can offer Google and another not,
	// from the same binary and the same configuration.
	Required bool `json:"required,omitempty"`
}

type AuthSession struct {
	// AccessTTL is the lifetime of the token that travels on every request.
	AccessTTL Duration `json:"access_ttl"`
	// RefreshTTL is how long an ordinary session lasts.
	RefreshTTL Duration `json:"refresh_ttl"`
	// RememberTTL is how long one lasts when somebody asked to stay signed in.
	RememberTTL Duration `json:"remember_ttl"`
	// RotationLeeway is how long a refresh token stays usable after it has been
	// exchanged, so a dropped response is a retry rather than a logout.
	RotationLeeway Duration `json:"rotation_leeway"`
	// IdentityTTL is the lifetime of the tenant-less credential somebody holds
	// between signing in and picking a tenant.
	IdentityTTL Duration `json:"identity_ttl"`
}

type AuthTenant struct {
	// Sources are tried in order, and the first that names a tenant wins. A
	// request that names none is not an error: a sign-in is allowed to arrive
	// without one.
	Sources []AuthTenantSource `json:"sources"`

	// Header is the header read by [TenantFromHeader].
	Header string `json:"header,omitempty"`
	// Query is the parameter read by [TenantFromQuery].
	Query string `json:"query,omitempty"`
	// DefaultSlugEnv names an environment variable holding the slug to fall back
	// to when the host names no tenant. It is the accommodation that lets a
	// host-based deployment be tried on localhost, where there is no subdomain
	// to read.
	DefaultSlugEnv string `json:"default_slug_env,omitempty"`
}

type AuthTenantSource string

type Cache struct {
	// Enabled says rig caches the reads it owns end to end — session and API key
	// verification. It is what makes server-go write the wiring.
	Enabled bool `json:"enabled"`

	// TTLSeconds is how long an answer may be reused with no invalidation
	// arriving. It is the backstop rather than the guarantee: a revocation is
	// published on the transaction that made it, and reaches every replica when
	// that transaction commits.
	//
	// Fractional for the reason [Throttle.IntervalSeconds] is: this is a number
	// somebody may reasonably want below a second.
	TTLSeconds float64 `json:"ttl_seconds"`

	// Channel is the Postgres NOTIFY channel invalidations travel on. Validated
	// as an identifier when the configuration was read, because it reaches
	// Postgres both quoted in a LISTEN and as a parameter to pg_notify.
	Channel string `json:"channel"`

	// MaxEntries bounds one cache. Past it the whole map is dropped rather than
	// swept — see runtime/cache.
	MaxEntries int `json:"max_entries,omitempty"`
}

type Check struct {
	Name       string `json:"name"`
	Expression string `json:"expression"`
}

type ChildLink struct {
	// Name is the HasMany accessor: HomeFixtures out of fixture.home_team_id.
	Name string `json:"name"`
	// Child is the resource name, Table the physical table behind it.
	Child string `json:"child"`
	Table string `json:"table"`
	// Column is the foreign key on the child's table.
	Column string `json:"column"`
	// Hook is the field on the child's parent-hooks struct this edge fills:
	// HomeTeam, matching the child's own [ParentLink.Name].
	Hook string `json:"hook"`
}

type Column struct {
	Name          string        `json:"name"`
	Comment       string        `json:"comment,omitempty"`
	CommentSource CommentSource `json:"comment_source"`

	// SQLType is the type as written, for example "text", "timestamptz",
	// "lesson_status" or "text[]". UDTName is the underlying pg_type name,
	// which differs for arrays and domains.
	SQLType string `json:"sql_type"`
	UDTName string `json:"udt_name,omitempty"`

	Nullable   bool   `json:"nullable"`
	HasDefault bool   `json:"has_default,omitempty"`
	Default    string `json:"default,omitempty"`

	// Identity is set for GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY.
	Identity bool `json:"identity,omitempty"`
	// Generated is set for GENERATED ALWAYS AS (expr) STORED. Such columns can
	// never be written, so they are read-only everywhere above this layer.
	Generated bool `json:"generated,omitempty"`

	CharMaxLength int `json:"char_max_length,omitempty"`
	NumericPrec   int `json:"numeric_precision,omitempty"`
	NumericScale  int `json:"numeric_scale,omitempty"`

	// Ordinal is the 1-based position in the table, preserved so generated
	// structs read in the same order as the CREATE TABLE.
	Ordinal int `json:"ordinal"`

	IsPrimaryKey bool   `json:"is_primary_key,omitempty"`
	ForeignKey   *FKRef `json:"foreign_key,omitempty"`

	// EnumType is the Postgres enum type name when this column is an enum.
	EnumType string `json:"enum_type,omitempty"`
	// ArrayElem is the element type name when this column is an array.
	ArrayElem string `json:"array_elem,omitempty"`
}

type ColumnRef struct {
	Table    string       `json:"table"`
	Name     string       `json:"name"`
	SQLType  string       `json:"sql_type"`
	Nullable bool         `json:"nullable"`
	Scan     ScanStrategy `json:"scan"`
}

type CommentSource string

type Document struct {
	IRVersion int    `json:"ir_version"`
	Tool      string `json:"generated_by"`

	API    API    `json:"api"`
	Schema Schema `json:"schema"`

	// Valid is false when the document was written despite validation errors.
	// Generators never run against an invalid document; it is emitted anyway so
	// that a broken project can still be inspected and repaired.
	Valid bool `json:"valid"`
	// contains filtered or unexported fields
}

type Duration time.Duration

type ElectricAuth string

type ElectricEndpoint struct {
	Auth ElectricAuth `json:"auth"`
	// Path is the live shape's route, for example "/api/v1/lesson/_stream".
	// It is written relative to the API's base path and expanded to the full
	// route when the document is frozen, the same way an endpoint's is.
	Path   string          `json:"path"`
	Params []ElectricParam `json:"params,omitempty"`

	// Fallback is whether this shape answers from the database when the sync
	// service cannot be reached, rather than answering 502.
	//
	// True for a table that asked for a shape at all, because a page whose list
	// *is* a shape renders nothing without its rows. False is for a shape whose
	// value is its freshness rather than its rows: a snapshot of who was looking
	// at this a moment ago, that then stops updating, is worth less than an empty
	// list.
	//
	// No omitempty, deliberately. The interesting value is the false one, and a
	// tag that hid it would leave the shape that opted out looking exactly like
	// one nobody had thought about.
	Fallback bool `json:"fallback"`
}

type ElectricParam struct {
	// Name is the query-string key exactly as clients send it.
	Name string `json:"name"`
	// Field is the Go identifier in the generated request struct.
	Field       string `json:"field"`
	Type        string `json:"type"`
	Optional    bool   `json:"optional,omitempty"`
	Description string `json:"description,omitempty"`
}

type Endpoint struct {
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Summary     string `json:"summary,omitempty"`
	Description string `json:"description,omitempty"`

	Method string `json:"method"`
	// Path is relative to the resource, for example "/{id}" or "".
	Path string `json:"path"`
	// Pattern is the full route in net/http form, for example
	// "GET /api/v1/lessons/{id}". Computed once when the document is frozen so
	// the router, the OpenAPI document, and the TypeScript client cannot
	// disagree about path shape.
	Pattern string `json:"pattern"`
	// AliasPatterns are additional routes dispatching to the same handler. Search
	// uses this to expose a POST fallback alongside the QUERY route, for
	// intermediaries that reject unfamiliar methods.
	AliasPatterns []string `json:"alias_patterns,omitempty"`

	OperationID string `json:"operation_id"`
	// Public answers without a credential.
	//
	// It means the endpoint does not require the claims lookup to succeed, not
	// that the lookup is skipped: an application that resolves a tenant from
	// the host rather than from a token still gets one, and a caller who does
	// present a credential is still identified by it. What changes is that a
	// caller who presents nothing is served instead of refused.
	Public bool `json:"public,omitempty"`

	// Permission is the RBAC key required to call this endpoint. Empty means a
	// valid session is enough.
	Permission string `json:"permission,omitempty"`

	// WidePermission is the key required to pass ?scope=all, on a read of an
	// owner-scoped resource. Empty everywhere else.
	//
	// Separate from Permission because they answer different questions and a
	// caller can hold one without the other. Reading your own notes and reading
	// everybody's are two grants, which is the whole point of the parameter.
	WidePermission string `json:"wide_permission,omitempty"`

	// File is the file column this endpoint acts on, set on the three rig
	// synthesizes per file column and nil on everything else.
	//
	// The upload's own [EndpointRequest.FileParts] says what the form carries;
	// this says which column the bytes end up on, which the download and the
	// delete need just as much and neither of them has a form.
	File *FileColumn `json:"file,omitempty"`

	Request   EndpointRequest    `json:"request"`
	Responses []EndpointResponse `json:"responses"`
	// Errors are the standard failure statuses this endpoint can return. They
	// are listed as bare codes rather than as full responses because every one
	// of them has the same body — the Error object — and spelling that out on
	// every endpoint would triple the size of the document without adding a
	// fact. Generators pair each code with the matching ErrorCode value.
	Errors []int        `json:"errors,omitempty"`
	Impl   EndpointImpl `json:"impl"`
}

type EndpointImpl struct {
	Kind EndpointKind `json:"kind"`
	// RepoMethod is the repository call the default implementation makes. Empty
	// for custom endpoints, which have no default.
	RepoMethod string `json:"repo_method,omitempty"`
	// ServiceMethod is the method name on the generated service interface.
	ServiceMethod string `json:"service_method"`
	// HandlerName is the generated HTTP handler's name.
	HandlerName string `json:"handler_name"`
}

type EndpointKind string

type EndpointRequest struct {
	// ContentTypes are the media types this endpoint accepts, most preferred
	// first.
	//
	// A list rather than one string because an endpoint can honestly accept two:
	// a create on a table with a file column takes either a JSON body or a
	// multipart form carrying the same JSON in one part and the bytes in
	// another. Everything else has exactly one, and a generator that wants "the"
	// content type takes the first.
	ContentTypes []string `json:"content_types,omitempty"`

	// FileParts are the file parts a multipart request carries, in the order the
	// server reads them. Empty on every endpoint that is JSON only.
	//
	// It is here because [EndpointRequest.ContentTypes] alone is not enough to
	// render a multipart request: it says the endpoint takes a form, and says
	// nothing about what the parts are called. A generator left to work that out
	// would re-derive the <role>_file_id convention from a field's name — which
	// is the convention the compiler exists to have already resolved, and which
	// three generators deriving separately would eventually disagree about.
	FileParts []FilePart `json:"file_parts,omitempty"`

	Headers     []Field `json:"headers,omitempty"`
	PathParams  []Field `json:"path_params,omitempty"`
	QueryParams []Field `json:"query_params,omitempty"`
	BodyParams  []Field `json:"body_params,omitempty"`
	// BodyObject names a whole object as the body, used instead of BodyParams.
	BodyObject string `json:"body_object,omitempty"`
}

type EndpointResponse struct {
	StatusCode  int    `json:"status_code"`
	Description string `json:"description,omitempty"`
	// ContentTypes are what this response can be. A list for symmetry with the
	// request, and because a download answers with whatever the file turned out
	// to be rather than with one type known at generation time.
	ContentTypes []string `json:"content_types,omitempty"`
	Headers      []Field  `json:"headers,omitempty"`
	BodyFields   []Field  `json:"body_fields,omitempty"`
	BodyObject   string   `json:"body_object,omitempty"`
}

type Enum struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Values      []EnumValue `json:"values"`
	// PgType binds this enum to the Postgres type it came from. Empty for enums
	// that exist only in the API, such as ErrorCode.
	PgType string `json:"pg_type,omitempty"`
}

type EnumValue struct {
	// Name is the Go and TypeScript identifier, for example "InProgress".
	Name string `json:"name"`
	// Wire is the literal on the wire and in Postgres, for example "in_progress".
	Wire        string `json:"wire"`
	Description string `json:"description,omitempty"`
}

type FKRef struct {
	Table    string `json:"table"`
	Column   string `json:"column"`
	OnDelete string `json:"on_delete,omitempty"`
	OnUpdate string `json:"on_update,omitempty"`
}

type Field struct {
	// Name is the Go and TypeScript identifier, for example "ManagerEmailAddress".
	Name string `json:"name"`
	// Wire is the JSON key, for example "managerEmailAddress".
	Wire string `json:"wire"`

	// Description is the human-readable text for this field, and the only copy
	// of it.
	//
	// Every generator that can carry a description must emit this one: a Go doc
	// comment, an OpenAPI `description`, a TypeScript doc comment. It is written
	// once — by the compiler, from the column comment or from the shape of the
	// thing — precisely so that a rule explained on a filter field is the same
	// sentence in the struct, in the schema, and in the client. A generator that
	// paraphrases it, or leaves it out, is how three descriptions of one field
	// start disagreeing.
	//
	// internal/gen/gentest.DescriptionsSurvive is the guard, and every generator
	// with a place to put a description calls it.
	Description string `json:"description,omitempty"`

	// Type is a primitive name or the name of an enum, object, or resource.
	Type string `json:"type"`
	// TypeKind resolves Type. Set when the document is frozen.
	TypeKind TypeKind `json:"type_kind"`
	// GoType is the concrete Go type for this field, including a leading * when
	// the field is nullable, for example "*string" or "time.Time".
	GoType string `json:"go_type,omitempty"`

	// Format narrows a primitive for documentation and client-side validation:
	// EmailAddress, URL, PhoneNumber, Color, CountryCode, RichText.
	Format string `json:"format,omitempty"`

	Modifiers []string `json:"modifiers,omitempty"`
	Default   string   `json:"default,omitempty"`
	Example   string   `json:"example,omitempty"`

	// ReadOnly fields never appear in a create or update body.
	ReadOnly bool `json:"read_only,omitempty"`
	// Immutable fields may be set on create but never updated, so they are
	// absent from the update body entirely.
	Immutable bool `json:"immutable,omitempty"`

	// Column binds this field to storage. Nil for computed or virtual fields.
	Column *ColumnRef `json:"column,omitempty"`
}

type FileColumn struct {
	// Role is the `<role>` from `<role>_file_id`, in the API's own casing, for
	// example "profileImage".
	Role string `json:"role"`
	// Column is the column itself, for example "profile_image_file_id". It is
	// what the upload writes and the download reads, and it is the one member
	// [FilePart] deliberately does not carry.
	Column string `json:"column"`
	// Field is the Go field on the row, for example "ProfileImageFileID".
	Field string `json:"field"`
	// Part is the multipart part's name, for example "profileImageFile".
	Part string `json:"part"`
	// Segment is the path segment the file endpoints sit under, for example
	// "profile-image-file". It is derived here so the router, the client and a
	// specification cannot spell it three ways.
	Segment string `json:"segment"`
	// Required says the column cannot be null.
	Required bool `json:"required,omitempty"`
}

type FilePart struct {
	// Name is the part's name on the wire, for example "profileImageFile". It
	// is what the server binds the bytes to, so a client that spells it
	// differently has uploaded a part nobody claimed.
	Name string `json:"name"`
	// Field is the Go field the part is named after, for example
	// "ProfileImageFileID" on a create and "Attachments" on an endpoint that
	// declared the part itself. A generator naming a member after the part
	// rather than after the column would produce a shape that reads nothing
	// like the row it belongs to — which is why a create's part takes its
	// member name from here and not from [FilePart.Name].
	Field string `json:"field"`
	// Role is the <role> from <role>_file_id, for example "profileImage". Empty
	// on a part a configuration declared, which has no column to take a role
	// from: what such a part is for is [FilePart.Description]'s to say.
	Role string `json:"role"`
	// Description is what the part carries, for a part a configuration
	// declared. Empty on a create's, whose role already says it.
	Description string `json:"description,omitempty"`
	// Required says the part has to be present: the column cannot be null, or
	// the configuration did not mark the part optional. It is the whole reason
	// a multipart create exists — a not-null file column is unreachable when
	// the row and its bytes are two requests.
	Required bool `json:"required,omitempty"`
	// Array says the part may repeat, carrying several files under one name.
	//
	// Never true of a create's, where one part is one column and a second copy
	// would be two files for one identifier. It is what an endpoint collecting
	// attachments needs, and it is the difference between an SDK member holding
	// one upload and one holding a list.
	Array bool `json:"array,omitempty"`
}

type Files struct {
	// Enabled says this project accepts uploads at all. It is what makes
	// server-go write the wiring.
	Enabled bool `json:"enabled"`
	// Expose says rig_file is projected as a read-only resource, so its url can
	// be read and synced.
	Expose bool `json:"expose,omitempty"`
	// Backend is where the bytes go: memory or s3.
	Backend string `json:"backend"`
	// S3 is the bucket, for a project whose backend is s3, and nil for one
	// whose backend is memory.
	//
	// Nil rather than a zero struct, so that a document for a project keeping
	// its uploads in memory is byte for byte what it was before this field
	// existed — which is what keeps the API revision of every such project from
	// moving because a backend it does not use became possible.
	S3 *FilesS3 `json:"s3,omitempty"`

	// MaxBytes caps one upload. A hard per-file cap and not a quota.
	MaxBytes int64 `json:"max_bytes"`
	// InlineTypes are the sniffed types served without an attachment
	// disposition. Everything else downloads.
	InlineTypes []string `json:"inline_types,omitempty"`

	// AbandonedAfterSeconds and RestoreWindowSeconds are the sweeper's two
	// rules, in seconds because a document is JSON and a duration is not.
	AbandonedAfterSeconds int64 `json:"abandoned_after_seconds"`
	RestoreWindowSeconds  int64 `json:"restore_window_seconds"`

	// CookieDownloads accepts the session cookie on file GET routes, so a
	// stored URL works in an img or a download link.
	CookieDownloads bool `json:"cookie_downloads,omitempty"`
}

type FilesS3 struct {
	// Bucket is the bucket name, and BucketEnv names an environment variable
	// holding it. Exactly one of them is set — a project that named both would
	// have given two answers to one question, and validation refuses it.
	Bucket    string `json:"bucket,omitempty"`
	BucketEnv string `json:"bucket_env,omitempty"`

	// Region is the bucket's region.
	Region string `json:"region,omitempty"`
	// Endpoint points at something other than AWS — MinIO, R2, a test double.
	// Setting it also selects path-style addressing, because virtual-host style
	// asks DNS to resolve a name almost nothing but AWS answers.
	Endpoint string `json:"endpoint,omitempty"`

	// AccessKeyEnv and SecretKeyEnv name the environment variables the
	// credentials are read from. Both empty at the point of use means the AWS
	// default credential chain, which is what an instance profile or IRSA
	// wants.
	AccessKeyEnv string `json:"access_key_env,omitempty"`
	SecretKeyEnv string `json:"secret_key_env,omitempty"`
}

type ForeignKey struct {
	Name           string   `json:"name"`
	Columns        []string `json:"columns"`
	ForeignTable   string   `json:"foreign_table"`
	ForeignColumns []string `json:"foreign_columns"`
	OnDelete       string   `json:"on_delete,omitempty"`
	OnUpdate       string   `json:"on_update,omitempty"`
}

type Index struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Unique  bool     `json:"unique,omitempty"`
	Method  string   `json:"method,omitempty"` // btree, gin, gist, hash, brin
	// Partial holds the WHERE predicate of a partial index, empty otherwise.
	Partial string `json:"partial,omitempty"`
}

type LinkTable struct {
	// Table is the join table itself. It is carried here because a relation
	// derived from a join table is otherwise unable to name the thing it
	// travels through, and that name is how configuration refers to it.
	Table string `json:"table"`

	LeftTable   string `json:"left_table"`
	LeftColumn  string `json:"left_column"`
	RightTable  string `json:"right_table"`
	RightColumn string `json:"right_column"`
}

type Monitoring struct {
	// Enabled says the generated server serves the page. A document carrying
	// this block always has it set, since a block that is off resolves to no
	// block at all.
	Enabled bool `json:"enabled"`
	// ServiceName is what the page calls this application, taken from the
	// project's own name.
	ServiceName string `json:"service_name"`
	// Addr is where the page listens, as host:port. Always set, because the
	// page has its own listener and rig defaults no part of one.
	Addr string `json:"addr"`
	// BasePath is where the page is mounted on that listener, resolved and
	// absolute.
	BasePath string `json:"base_path"`
	// MaxTraces is how many requests the page lists, newest first.
	MaxTraces int `json:"max_traces"`
	// MaxLogs is how many log lines the page reads, newest first.
	MaxLogs int `json:"max_logs"`
	// PasswordEnv names the variable the page reads its password from.
	PasswordEnv string `json:"password_env"`
	// Password is the literal from rig.yaml, and empty in every project that
	// took the warning.
	Password string `json:"password,omitempty"`
	// Allow is the addresses that may reach the page, as CIDR ranges or single
	// addresses. Empty allows any, and it narrows the password rather than
	// standing in for it.
	Allow []string `json:"allow,omitempty"`
}

type Notifications struct {
	// Enabled says this project has an inbox. It is what makes server-go write
	// the wiring, and what keeps rig's notification tables in the schema.
	Enabled bool `json:"enabled"`
	// Expose says the inbox is projected as a resource as well, so it gets the
	// filter grammar and a generated client. The hand-written routes exist
	// either way.
	Expose bool `json:"expose,omitempty"`

	// DefaultDigest is what an account with no setting for a channel gets.
	DefaultDigest string `json:"default_digest"`

	// ClaimTTLSeconds is how long a dispatcher's claim is honoured, and the rest
	// of the retry arithmetic beside it. Seconds because a document is JSON and
	// a Go duration in one is either unreadable or has to be parsed by everybody.
	ClaimTTLSeconds int64 `json:"claim_ttl_seconds"`
	// SendTimeoutSeconds bounds one call into a channel, and is necessarily
	// below ClaimTTLSeconds: a send that may outlive its own lease is a send
	// whose row another dispatcher has already taken.
	SendTimeoutSeconds int64 `json:"send_timeout_seconds"`
	MaxAttempts        int   `json:"max_attempts"`
	BackoffBaseSeconds int64 `json:"backoff_base_seconds"`
	// BackoffCapSeconds is the longest one wait may be. It is what makes a long
	// attempt count a schedule rather than a sleep: doubling from a minute
	// fourteen times is five days, and capped at an hour it is eight.
	BackoffCapSeconds int64 `json:"backoff_cap_seconds"`
	// RetentionSeconds is how long a read and deleted inbox line is kept.
	RetentionSeconds int64 `json:"retention_seconds"`
}

type Object struct {
	Name        string  `json:"name"`
	Description string  `json:"description,omitempty"`
	Fields      []Field `json:"fields"`
	Origin      Origin  `json:"origin"`
}

type OpenAPI struct {
	// JSONPath is where the JSON rendering is served, for example
	// "/api/v1/openapi.json".
	JSONPath string `json:"json_path"`
	// YAMLPath is where the YAML rendering is served.
	YAMLPath string `json:"yaml_path"`

	// Import is the package the document is embedded in: the project's module
	// path joined to the openapi generator's output directory, taken from the
	// module root rather than from the directory holding rig.yaml. Those are the
	// same directory in a flat project and are not in a two-half one, and the
	// nearest go.mod is what says which.
	//
	// Derived rather than configured, because there is exactly one right answer
	// and everything it needs is already written down. A generator reads it
	// instead of asking the project, which is what keeps the package that
	// declares the embed and the router that imports it from being told two
	// different things.
	Import string `json:"import"`

	// Package is the name that package declares, which is [Import]'s last
	// segment.
	//
	// Stored rather than derived twice: the generator that writes the package
	// clause and the generator that qualifies a reference with it have to agree,
	// and a directory name Go could not use as a package name is refused when
	// the configuration is read rather than discovered by a build.
	Package string `json:"package"`
}

type OrderTerm struct {
	Column string `json:"column"`
	Desc   bool   `json:"desc,omitempty"`
}

type Origin string

type ParentLink struct {
	// Name is the accessor, matching the BelongsTo relation: HomeTeam out of
	// home_team_id. It is what the two hook fields are named after.
	Name string `json:"name"`
	// Parent is the resource name, Table the physical table behind it.
	Parent string `json:"parent"`
	Table  string `json:"table"`
	// Column is the foreign key on this resource's own table.
	Column string `json:"column"`
}

type Permission struct {
	Key         string `json:"key"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// Resource is the resource it was derived from, so a rename can be reported
	// against something more useful than a string.
	Resource string `json:"resource,omitempty"`
	// Action is read, write, delete, or the name of a custom endpoint.
	Action string `json:"action,omitempty"`
}

type PgEnum struct {
	Name    string        `json:"name"`
	Comment string        `json:"comment,omitempty"`
	Values  []PgEnumValue `json:"values"`
}

type PgEnumValue struct {
	Value string `json:"value"`
	// Description comes from the table configuration; Postgres cannot comment
	// on individual enum labels.
	Description string `json:"description,omitempty"`
}

type Presence struct {
	// Enabled says this project tracks presence. It is what makes server-go
	// write the wiring, and what keeps rig_presence in the schema.
	Enabled bool `json:"enabled"`
	// Expose says presence is projected as a read-only resource as well, so it
	// gets the filter grammar and a generated client. The hand-written routes and
	// the live shape exist either way.
	Expose bool `json:"expose,omitempty"`

	// TTLSeconds is how long a session stays present after its last heartbeat.
	// Seconds because a document is JSON and a Go duration in one is either a
	// number nobody can read or a string every consumer has to parse.
	TTLSeconds int64 `json:"ttl_seconds"`
	// HeartbeatSeconds is how often a browser should confirm it is still there.
	// It is carried so the heartbeat route can answer with it, which is what puts
	// the interval on the server's side of the wire.
	HeartbeatSeconds int64 `json:"heartbeat_seconds"`
	// SweepSeconds is how often the in-process sweeper runs. Negative leaves the
	// generated task as the only sweeper.
	SweepSeconds int64 `json:"sweep_seconds"`
	// GraceSeconds is how long past the TTL a row survives, which is what keeps
	// the reader's arithmetic and the sweeper's from disagreeing.
	GraceSeconds int64 `json:"grace_seconds"`
}

type Publication struct {
	Name string `json:"name"`
	// AllTables is a publication declared FOR ALL TABLES, which carries every
	// table in the database including ones created after it.
	AllTables bool `json:"all_tables,omitempty"`
	// Owned says this publication belongs to the role rig connected as, which is
	// the role that runs migrations.
	//
	// It is the one fact that tells a publication a migration wrote from one the
	// sync service created for itself, and the two are worth telling apart even
	// when they share a name. The sync service makes
	// `electric_publication_default` on first connection and owns it; a migration
	// that creates the same publication first owns it instead, and that is the
	// arrangement that makes live sync work for a role owning no tables. Only the
	// owner distinguishes them.
	Owned bool `json:"owned,omitempty"`
}

type Relation struct {
	Name   string       `json:"name"`
	Kind   RelationKind `json:"kind"`
	Target string       `json:"target"` // resource name

	LocalColumn   string     `json:"local_column,omitempty"`
	ForeignTable  string     `json:"foreign_table,omitempty"`
	ForeignColumn string     `json:"foreign_column,omitempty"`
	LinkTable     *LinkTable `json:"link_table,omitempty"`

	// Embed includes the related rows in read responses.
	Embed bool `json:"embed,omitempty"`
}

type RelationKind string

type ReplicaIdentity string

type Replication struct {
	// WALLevel is the server's wal_level. Logical replication needs "logical",
	// and it cannot be turned on after Postgres has started.
	WALLevel string `json:"wal_level,omitempty"`
	// Publications is every publication in the database, sorted by name,
	// whether or not it carries anything.
	Publications []Publication `json:"publications,omitempty"`
}

type Resource struct {
	Name        string `json:"name"`         // Lesson
	Plural      string `json:"plural"`       // Lessons
	PathSegment string `json:"path_segment"` // lessons
	Description string `json:"description,omitempty"`

	// Unexposed keeps a table out of the API while keeping its model and
	// repository.
	//
	// The authentication foundation is why this exists. Sessions and API keys
	// need generated persistence and must not have generated CRUD endpoints:
	// nothing good comes of a REST interface for the token table. Saying so on
	// the resource rather than deleting it is what lets the data layer stay
	// generated while the API layer stays silent.
	//
	// It is negative so that the zero value is the ordinary case.
	//
	// It is not on its own a reason to generate nothing:
	// [Resource.Unreachable] is that, and it asks about Foundation too.
	Unexposed bool `json:"unexposed,omitempty"`

	// Foundation says rig created this table: it is one of the `rig_` tables a
	// module's migration set carries, and rig ships the configuration that
	// decides how it projects.
	//
	// What reads it is the stub writers. A stub is a file rig creates once and
	// then never touches, for a project to put its own rules in — and for a
	// table the project did not create, has no migration for and cannot change,
	// the rules are usually that there are none. Three of the four such stubs in
	// this repository's own examples were byte-identical no-ops, and two of those
	// were not imported by anything.
	//
	// It also decides, with Unexposed, whether any Go is written for the table
	// at all — see [Resource.Unreachable]. That is a correctness question, and
	// the answer is safe to lean on for the reason the flag is computed the way
	// it is: it comes from the project's migrations or its configuration rather
	// than from the `rig_` prefix, so a project with `auth.own` — which has
	// taken the schema over — has none of these, and gets its stubs and its
	// generated model both.
	Foundation bool `json:"foundation,omitempty"`

	Operations []string `json:"operations"`
	// Public names the operations that answer without a credential, generated
	// and custom alike. An endpoint carries the resolved flag; this is the
	// declaration the endpoints are built from.
	Public    []string        `json:"public,omitempty"`
	Fields    []ResourceField `json:"fields"`
	Endpoints []Endpoint      `json:"endpoints"`

	// Files are this resource's file columns, in the order they appear on the
	// table. Each one yields an upload, a download and a delete endpoint, two
	// permission keys, and a part on the multipart form the create also accepts.
	//
	// Resolved once, where the schema is still in scope: recognizing one means
	// reading the table's foreign keys, and by the time a generator holds a
	// resource the constraints are gone. A generator that re-derived it from a
	// field name would be re-deriving the convention the compiler exists to have
	// already settled.
	Files []FileColumn `json:"files,omitempty"`

	// Notifiable says this table is joined to rig_notification by a link table,
	// so notifications can be about its rows.
	//
	// It is derived from the schema rather than declared: any link table one
	// side of which is rig_notification makes the other side notifiable, so the
	// recommended name — blog_post_notification — is a recommendation and
	// nothing depends on it. There is nothing for a name to say here that the
	// foreign key does not.
	//
	// A notifiable resource's rules interface grows two required methods: when
	// notifications about a row are due, and — at the moment of sending — who
	// should hear about it.
	Notifiable bool `json:"notifiable,omitempty"`

	// Cached says this resource's Get is held in memory between requests, keyed
	// by the row and the scope the read was made under, and withdrawn by a
	// Postgres NOTIFY published on the transaction of every write the generated
	// repository makes to the row.
	//
	// Declared per table rather than derived, because it is a promise about the
	// application as much as a fact about the schema: rig can only publish the
	// withdrawal from writes it makes, so a project that writes this table
	// through Store.Pool or with raw SQL from inside a dbhook is a project where
	// this serves a stale row until the entry expires. Nothing in the schema says
	// whether that is true, so nothing but a person can turn this on.
	//
	// It needs [API.Cache], which is what owns the channel the withdrawals
	// travel on.
	Cached bool `json:"cached,omitempty"`

	// Parents are the resources this one points at, one per foreign key, in the
	// order the columns appear on the table. Each becomes a pair of hook fields
	// the service layer may fill in.
	Parents []ParentLink `json:"parents,omitempty"`

	// Children are the resources that point at this one, in the order they are
	// told about a delete.
	//
	// The order is derived — referencing tables before referenced ones — and
	// resolved here rather than in a generator, because it is a fact about the
	// whole schema and a generator holds one resource at a time.
	Children []ChildLink `json:"children,omitempty"`

	// Storage is nil for a virtual resource with no table behind it.
	Storage *ResourceStorage `json:"storage,omitempty"`
	// Electric is set when the resource exposes a live-sync shape endpoint.
	Electric *ElectricEndpoint `json:"electric,omitempty"`
}

type ResourceField struct {
	Field `json:",inline"`
	// Operations is some subset of Create, Read, Update.
	Operations []string `json:"operations"`
}

type ResourceStorage struct {
	Table      string   `json:"table"`
	PrimaryKey []string `json:"primary_key"`

	// Tenant is the column every generated query is scoped by.
	Tenant *ColumnRef `json:"tenant,omitempty"`

	// Owner is the column a read is narrowed by when the table asked for it —
	// the account that created the row.
	//
	// Set only by `access: { scope: own }`, because it changes what a request
	// answers with and that is not something to infer from a column being
	// present. Plenty of tables record who created a row without meaning that
	// nobody else may read it.
	Owner *ColumnRef `json:"owner,omitempty"`

	Audit      *AuditColumns `json:"audit,omitempty"`
	SoftDelete *SoftDelete   `json:"soft_delete,omitempty"`
	Snapshot   *Snapshot     `json:"snapshot,omitempty"`

	DefaultOrder []OrderTerm `json:"default_order,omitempty"`
	Relations    []Relation  `json:"relations,omitempty"`

	Sortable   []string `json:"sortable,omitempty"`
	Filterable []string `json:"filterable,omitempty"`
}

type ScanStrategy string

type Schema struct {
	// Name is the Postgres schema, almost always "public".
	Name string `json:"name"`

	Tables []Table  `json:"tables"`
	Enums  []PgEnum `json:"enums"`

	// Replication is what the server says about logical replication.
	//
	// Nil means nobody looked: a schema dump written before rig read these
	// facts, or a hand-written fixture. A live introspection always sets it,
	// even when the database has no publication at all, which is what lets a
	// rule tell "looked and found none" from "never looked".
	Replication *Replication `json:"replication,omitempty"`
}

type Server struct {
	// Name identifies the deployment, and becomes an identifier in every
	// generated SDK: production is Go's ServerProduction and TypeScript's
	// servers.production. Empty only for the one nameless entry a project still
	// configuring the deprecated per-generator option produces.
	Name string `json:"name,omitempty"`

	// URL is where that deployment answers. The API's own base path is appended
	// to it, so it is not repeated here.
	URL string `json:"url"`

	// Description is one line about what the deployment is for. It reaches the
	// OpenAPI document and the doc comment beside the generated constant.
	Description string `json:"description,omitempty"`

	// Default marks the deployment a caller who names none receives, and exactly
	// one entry in a document carries it. The project resolves "nobody claimed
	// it, so the first one" before this is written, so three generators do not
	// each implement the same rule.
	Default bool `json:"default,omitempty"`
}

type Snapshot struct {
	VersionType *ColumnRef `json:"version_type"`
	FromID      *ColumnRef `json:"from_id"`
	FromAt      *ColumnRef `json:"from_at"`
	// IgnoreColumns are not replayed when a snapshot is restored: the live
	// row's values win. They are still copied into the snapshot itself.
	IgnoreColumns []string `json:"ignore_columns,omitempty"`
}

type SoftDelete struct {
	Column *ColumnRef `json:"column"`
	Actor  *ColumnRef `json:"actor,omitempty"`
	// ActorKey is the API key the deletion came through, when the table has a
	// column for it. It is stamped beside Actor rather than instead of it.
	ActorKey *ColumnRef `json:"actor_key,omitempty"`
	// RestoreWindowDays bounds how long a deleted row stays restorable.
	RestoreWindowDays int `json:"restore_window_days"`
}

type Table struct {
	Name    string    `json:"name"`
	Comment string    `json:"comment,omitempty"`
	Kind    TableKind `json:"kind"`

	Columns    []Column   `json:"columns"`
	PrimaryKey []string   `json:"primary_key,omitempty"`
	Uniques    [][]string `json:"uniques,omitempty"`

	Indexes     []Index      `json:"indexes,omitempty"`
	ForeignKeys []ForeignKey `json:"foreign_keys,omitempty"`
	Checks      []Check      `json:"checks,omitempty"`

	// Publications names every publication that carries this table, sorted,
	// including one declared FOR ALL TABLES. Empty on a table with live sync
	// means the stream would never emit a row.
	Publications []string `json:"publications,omitempty"`
	// Unlogged is a table whose relpersistence is 'u'. It writes no WAL, so
	// logical replication cannot see it at all.
	Unlogged bool `json:"unlogged,omitempty"`
	// ReplicaIdentity is what an UPDATE or a DELETE on this table puts in the
	// WAL for the row as it was. Live sync needs [ReplicaIdentityFull].
	//
	// Empty means nobody looked — a schema dump written before rig read this, or
	// a hand-written fixture — which is what lets the rule over it be an error
	// rather than a guess. Same convention as [Schema.Replication], one level
	// down.
	ReplicaIdentity ReplicaIdentity `json:"replica_identity,omitempty"`

	// LinkTable is set when this table is a pure many-to-many join: its primary
	// key is exactly two foreign-key columns. Such tables become relations on
	// the resources they join, never resources of their own.
	LinkTable *LinkTable `json:"link_table,omitempty"`
}

type TableKind string

type Throttle struct {
	Enabled bool `json:"enabled"`

	// APIKey, Account and Tenant apply to a caller who said who they were; IP
	// applies only to one who did not. A zero limit is one nobody configured,
	// and the runtime fills it from its own defaults.
	APIKey  ThrottleLimit `json:"api_key"`
	Account ThrottleLimit `json:"account"`
	Tenant  ThrottleLimit `json:"tenant"`
	IP      ThrottleLimit `json:"ip"`

	// IntervalSeconds is how long a replica may count locally before publishing.
	// It is the accuracy of the limit stated as time, so it belongs in the
	// document beside the numbers it qualifies.
	//
	// Fractional, unlike every other duration here: sub-second is a reasonable
	// thing to ask for from something that runs on every request, where a
	// sub-second *window* is not.
	IntervalSeconds float64 `json:"interval_seconds,omitempty"`

	// Routes are extra limits on particular patterns, on top of the per-caller
	// ones.
	Routes []ThrottleRoute `json:"routes,omitempty"`

	// Exempt are patterns nothing applies to.
	Exempt []string `json:"exempt,omitempty"`
}

type ThrottleLimit struct {
	Max           int   `json:"max,omitempty"`
	WindowSeconds int64 `json:"window_seconds,omitempty"`
}

type ThrottleRoute struct {
	// Pattern is the route as the router registers it, matched against what
	// net/http reports rather than against a path.
	Pattern       string `json:"pattern"`
	Max           int    `json:"max"`
	WindowSeconds int64  `json:"window_seconds"`
}

type Tracing struct {
	// Enabled says the generated server, repositories and client open spans.
	// A document carrying this block always has it set, since a block that is
	// off resolves to no block at all.
	Enabled bool `json:"enabled"`
	// ServiceName is what this application is called in a collector, taken from
	// the project's own name.
	ServiceName string `json:"service_name"`
}

type TypeKind string

type Web struct {
	// Origin is where the front end is served, as scheme://host[:port] with
	// nothing after the host. Empty when OriginEnv carries it instead.
	Origin string `json:"origin,omitempty"`

	// OriginEnv is the environment variable the origin comes from, for the
	// deployment that has a different front end per environment. Empty when the
	// origin is written in the file.
	//
	// Both may be set: the file's value is the default and the variable wins,
	// which is how [Auth.OAuth]'s base URL already behaves.
	OriginEnv string `json:"originEnv,omitempty"`

	// CallbackPath is the path on Origin that receives a finished sign-in.
	// Always set; the project fills in the default.
	CallbackPath string `json:"callbackPath"`

	// CORS is what a preflight from that front end is answered with.
	CORS WebCORS `json:"cors"`
}

type WebCORS struct {
	// AllowedOrigins are origins beyond [Web.Origin] that may call this API — an
	// administrative front end, most often. Each is scheme://host[:port], or one
	// leading *. label for a wildcard.
	AllowedOrigins []string `json:"allowedOrigins,omitempty"`

	// AllowedOriginsEnv is the environment variable that replaces the list
	// above, as a comma-separated string. Always set; the project fills in the
	// default.
	AllowedOriginsEnv string `json:"allowedOriginsEnv"`

	// MaxAgeSeconds is how long a browser may cache a preflight. Seconds rather
	// than a duration because that is what the header carries and what every
	// generator would otherwise convert.
	MaxAgeSeconds int64 `json:"maxAgeSeconds"`
}